key option or store it on the account. Similarweb reads it as the api_key query parameter.
Similarweb has no product called the Digital Rank API; rank data comes from the Website Traffic API (per-domain rank routes), the App Rank route and the Top Sites list. These nine operations are those routes.
Things to know before you query:
- Domains must be bare and lower case. Send
cnn.com, notCNN.COMand not a URL with a path. Similarweb answers a capitalised domain with a 401 rather than data, so the plugin lower-cases the domain and trims it before sending. - Both dates or neither.
websites.globalRankandwebsites.countryRanktakestart_dateandend_dateasYYYY-MM. Sending only one is accepted but answered with the default 28-day window, so the schema rejects it instead of returning the wrong months. - Global rank covers desktop and mobile together, one point per month. There is no desktop-only or mobile-only variant of this route.
- Industry rank is a single reading. It returns the domain’s industry and its rank in that industry worldwide, with no date range.
- App rank needs a matching store and device. Use
androidphonewith Google, andiphoneoripadwith Apple. The plugin rejects a mismatched pair, because the API answers it with an empty series rather than an error. Callapps.describefor the accepted stores, modes and countries. - Errors are plain text, not JSON. A 401 is either the literal
invalid API key(no key or a wrong one) orData not found(a domain it has no data on, or a mistyped one); the plugin treats the second as not-found, not as an auth failure. A 403 means either a bad key or an exhausted credit balance, and Similarweb documents no way to tell them apart. Checkcapabilities.getandusage.getbefore concluding the key is wrong. - Rate limit. Similarweb allows 10 requests per second per account and answers 429 past it. Core retries those three times with backoff.
- Credits. Most routes cost data credits per result, and
usage.getitself is free.usage.getreturns the allowance and what is left;usedis derived from the two.
- 9 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the Similarweb API key before the first call: More: API Key
pnpm corsair setup --plugin=similarweb --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Read a domain’s global rank for three monthsWhat’s next
API reference
Every
similarweb.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.