Authentication & limits¶
Let's get you connected! The first thing you'll want to know is how to authenticate your requests. While you're here, we also encourage you to at least skim the documentation on limits.
Authentication¶
Local development¶
You can get started developing locally without any special effort or cost. If your application
is running via a development web server accessed via localhost
or 127.0.0.1
, we'll treat your
requests as coming from a free plan. Note that this is designed for convenience of development on
a single machine, and is rate limited accordingly. If you start receiving HTTP 429 responses,
please sign up for an account (it's free!) and use an API key.
Domain-based authentication¶
Domain-based authentication is the easiest form of authentication for production web apps. No additional application code is required, and you don't need to worry about anyone scraping your API keys. We recommend this for most browser-based applications.
- Sign in to the client dashboard.
- Click "Manage Properties."
- Under "Authentication Configuration," click the button to add your domain.
Still getting a 401 Unauthorized response?
Domain authentication usually "just works" but sometimes it doesn't. These are a few common issues related domain authentication.
Referrer-Policy
is set tono-referrer
. Some platforms, such as Azure Static Web Apps, do this by default. Relaxing this header to something likestrict-origin-when-cross-origin
(if your site uses HTTPS;origin-when-cross-origin
if using HTTP) will let us authenticate your requests while preserving privacy.- The
Origin
orReferer
domain is a nested subdomain. If your site is hosted ona.b.example.com
, set the subdomain toa
and the domain tob.example.com
as shown in the screenshot below:
API keys¶
You will need to include an API key with each request that is made outside a web browser.
Generating and Revoking API keys¶
You can manage your API keys in the client dashboard.
- Sign in to the client dashboard. (If you don't have an account yet, sign up for free; no credit card required!)
- Click "Manage Properties."
- If you have more than one property (ex: for several websites or apps), make sure you have selected the correct property from the dropdown at the top of the page.
- Under "Authentication Configuration," you can generate, view or revoke your API key.
Video: How to generate your API key¶
Security¶
Please take care not to expose your API key. You generally should use domain-based authentication for web browser applications. Use API keys only for requests coming from outside a web browser or for local development when you need to make requests in excess of the rate limit for keyless access.
Warning
Note that security of API keys is your responsibility, and requires special care whenever the application has end users outside your organization. While major mobile platforms like iOS encrypt and sandbox applications, all bets are off on a jailbroken device. You can mitigate these risks by having your app pull an API key from your servers at regular intervals, ideally via an authenticated endpoint. Always store secrets securely whenever possible. For mobile applications, most platforms have a secure credential storage and retrieval API, and we highly recommend using that.
Using your API key¶
You can use API keys in two ways. The simplest is to add a query string parameter api_key=YOUR-API-KEY
to your request URL. You can alternately add an Authorization
header
with the value Stadia-Auth YOUR-API-KEY
.
Examples¶
https://api.stadiamaps.com/tz/lookup/v1/?api_key=YOUR-API-KEY
Authorization: Stadia-Auth YOUR-API-KEY
Limits¶
We have two forms of limits: the features you can access with your plan and request-level limits. You can see the list of features included with each plan on our pricing page. In this documentation, we try to highlight when a feature is only available on certain plans with something like this (which indicates that a feature is available only on paid plans):
Free
Starter
Standard
Professional
Our convention is to not include a plan grid if a feature is available to all users. If the feature(s) discussed on a page are only available to a subset of plans, we will either put a plan grid at the top of the page (if it applies to the entire page) or under specific headings where limitations apply.
Our plans each come with request limits as specified on our pricing page. After your request credits and grace threshold are exhausted, our default action is to hard limit until the start of the next billing cycle or plan upgrade. This protects you from unexpected bills. If you want to keep serving requests beyond the plan limits, we offer opt-in pay-as-you-go billing with simple, discounted pricing on the additional credits. See our pricing page for details.
We will send an automated email if your account has been hard limited.
Free tier restrictions¶
We offer a free tier for development, evaluation, and non-commercial use. Other uses of the free tier are not permitted and require a paid subscription.
You can upgrade your free subscription to one of our paid plans at any time.
Rate Limits¶
We reserve the right to impose rate limits on customers who are abusive or disruptive of service. We also enforce rate limits on local development as noted above.
Complexity limits¶
We impose the following limits universally across on our Geospatial APIs. If you have a more demanding use case, send us a message, and we can discuss your use case.
Routing¶
Costing/Mode of Travel | Max Route Locations |
---|---|
Automobile and truck | 20 |
All others | 50 |
Time/distance matrix¶
All matrix requests have a limit of 1000 elements, regardless of the costing/mode of travel. A matrix request with 3 inputs and 5 outputs has 3 x 5 = 15 cells. This means you could send a 10 x 10 or 2 x 50 matrix request (each having 100 cells), but not 40 x 30 as it has 1200 cells.
All matrix endpoints (including optimized routing) have a limit of 1000 elements, regardless of the costing/mode of travel. A matrix request with 3 inputs and 5 outputs has 3 x 5 = 15 elements. This means you could send a 100 x 10 or 20 x 50 matrix request (each having 1000 elements), but not 40 x 30 as it has 1200 elements.