Stadia Maps Management API (Beta)¶
The Management API is designed to allow our customers to manage their properties, domains, API keys, and applicable plans without having to visit our management page. This is particularly helpful if you have many properties to manage or would like to integrate our maps into an automated system.
Our Management API is a REST API and powered by the popular Django REST Framework. We offer a web browsing mode so you can informally familiarize yourself with the layout of the API.
Note: API access is currently a beta feature, so it is not yet enabled for all accounts. If you would like access, please contact us at info@stadiamaps.com, and we can set it up for you.
Authentication¶
Our API uses token-based authentication via the Authorization
HTTP header, so
to authorize your requests with our API, you will need to obtain your API key
first.
To find your API key, head over to your management panel and account details, and if you have API access, you should see your API key.
To use the key, please add this header to all of your API requests:
Authorization: Token <your api key>
The API will return a 403 Forbidden
error if you do not provide a token or
provide an invalid token, along with details of the error in the response.
Quick Start¶
To get started with our API, let's walk through a quick example of creating a property and an associated domain. We'll use the popular Python library requests for our examples.
Create Property with Domain¶
import requests
API_TOKEN = 'Token <your API token>'
# Create a session and attach the authorization header.
api_session = requests.Session()
api_session.headers['Authorization'] = API_TOKEN
# Create a property with the desired name.
property_resp = api_session.post(
'https://client.stadiamaps.com/api/v1/properties/',
json={'name':'My API Property'}
)
# Ensure the request succeeded.
assert property_resp.status_code == 201
# Create a domain attached to that property. But please use another domain name!
# example.com is only for demonstration purposes. :)
domain_resp = api_session.post(
'https://client.stadiamaps.com/api/v1/domains/',
json={'property_id': property_resp.json()['id'],
'base_domain': 'example.com',
'wildcard': True,
}
)
# Ensure the request succeeded.
assert domain_resp.status_code == 201
If all went well, you should be able to make requests with your map hosted on example.com (or any subdomain).
Endpoints¶
All endpoints are based on the URL https://client.stadiamaps.com/api/v1/.
/properties/
¶
Use this endpoint to manipulate Properties. Most APIs will start with this endpoint by creating a new property.
Methods
POST /
- creates a new propertyGET /
- returns a list of all properties associated with an accountGET /<property_id>/
- returns the details of a propertyGET /<property_id>/stats/
- returns the last 30 days of usage for a property (as a list of Stat objects)PUT /<property_id>/
- updates a propertyPATCH /<property_id>/
- partially updates a propertyDELETE /<property_id>/
- deletes a property (along with any associated domains or API keys)
/domains/
¶
Use this endpoint to manipulate Domains.
Methods
POST /
- creates a new domainGET /
- returns a list of all domains associated with an accountGET /<domain_id>/
- returns the details of a domainPUT /<domain_id>/
- updates a domainPATCH /<domain_id>/
- partially updates a domainDELETE /<domain_id>/
- deletes a domain
/api_keys/
¶
Use this endpoint to manipulate API Keys.
Methods
POST /
- creates a new API keyGET /
- returns a list of all API keys associated with an accountGET /<key>/
- returns the details of an API keyPOST /<key>/recycle/
- updates thekey
value (replaces the current API key with a new key) Warning: this will invalidate the previous API key and return a new API key, use with caution.PUT /<key>/
- updates an API keyPATCH /<key>/
- partially updates an API keyDELETE /<key>/
- deletes an API key
/plans/
¶
Use this endpoint to fetch a list of Plans.
Methods
GET /
- returns a list of all available Plans for an account
Models¶
Our APIs closely follow our UI, so you can expect rough correlation between what you're used to seeing in the API and what you're seeing in the API.
Property¶
A property correlates to an app, web or mobile. All domains and API keys are connected to a property; usage tiers are also managed at the property level.
Fields
Field Name | Field Type | Attributes | Description |
---|---|---|---|
id | integer | read-only | the primary key for the Property |
account_id | integer | read-only | your account ID |
name | string | required, 500 chars or less | a descriptive name |
stripe_plan_key | string | default: free |
the selected usage tier, a stripe_id from a Plan |
Stat¶
A stat represents one day of usage for a property. Each stat has an associated kind that represents the type of request (e.g., map views or routing).
Field Name | Field Type | Attributes | Description |
---|---|---|---|
count | integer | the total usage for this kind for this date |
|
kind | string | one of static , vector , raster , route |
|
date | date | ISO 8601 date format |
Notes:
- For quota purposes,
static
,vector
, andraster
are grouped together against your map view quota.route
is a single value representing yourrouting
quota usage. - Dividing the map or routing quota by your property's plan map_views_per_day yields your usage percentage for a day.
Domain¶
Domains allow access to our services via an authorized domain name.
Field Name | Field Type | Attributes | Description |
---|---|---|---|
id | integer | read-only | primary key for the Domain |
property_id | integer | required | primary key for a Property |
base_domain | string | required | must be a non-TLD domain name (e.g., example.com) |
wildcard | boolean | default: False |
determines if the base domain is treated as *.<base_domain> |
subdomain | string | a subdomain prepended to the base_domain , (e.g., www.<base_domain> ) |
Note: The wildcard
and subdomain
fields should be considered mutally
exclusive. If wildcard
is set, the subdomain
field will be ignored.
API Key¶
API keys allow access to our maps via a header or request URL.
Field Name | Field Type | Attributes | Description |
---|---|---|---|
key | uuid | read-only | the API key itself and the primary key for the record |
property_id | integer | required | primary key for a Property |
kind | string | read-only | value is always master |
Note: The key
value is the value to be used in the query string or header argument of map or routing requests.
Plan¶
Plans encapsulate all the information related to a usage tier. All fields in this model are read-only.
Field Name | Field Type | Attributes | Description |
---|---|---|---|
stripe_id | string | the primary key for the Plan | |
name | string | a human-readable name | |
amount | float | the cost of a plan, paired with currency results in the actual cost | |
currency | string | the currency of a plan (in the form of USD or CHF ) |
|
map_views_per_day | string | the number of map views or routing requests allowed in a day |
Note: map_views_per_day
is a soft limit in all paid plans.
Additional Documentation¶
Additional documentation may be found in the API itself by using OPTIONS
or
browsing it in a web browser.
OpenAPI / Swagger¶
A reasonably complete OpenAPI / Swagger specification exists at https://client.stadiamaps.com/api/docs/. You can generate an API client in your favorite language using any OpenAPI generator. You can find the JSON spec here.
Bugs¶
Please report any bugs discovered to info@stadiamaps.com. We hope you don't find any, but please let us know if you do!