Stadia Maps Client API (Beta)¶

The Client API is designed to allow our customers to manage their properties, domains, API keys, and applicable plans without having to visit our mangement page. This is particularly helpful if you have many properties to manage or would like to integrate our maps into an automated system.

Our Client 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 property
• GET / - returns a list of all properties associated with an account
• GET /<property_id>/ - returns the details of a property
• GET /<property_id>/stats/ - returns the last 30 days of usage for a property (as a list of Stat objects)
• PUT /<property_id>/ - updates a property
• PATCH /<property_id>/ - partially updates a property
• DELETE /<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 domain
• GET / - returns a list of all domains associated with an account
• GET /<domain_id>/ - returns the details of a domain
• PUT /<domain_id>/ - updates a domain
• PATCH /<domain_id>/ - partially updates a domain
• DELETE /<domain_id>/ - deletes a domain

/api_keys/¶

Use this endpoint to manipulate API Keys.

Methods

• POST / - creates a new API key
• GET / - returns a list of all API keys associated with an account
• GET /<key>/ - returns the details of an API key
• POST /<key>/recycle/ - updates the key 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 key
• PATCH /<key>/ - partially updates an API key
• DELETE /<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, and raster are grouped together against your map view quota. route is a single value representing your routing 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/.

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!