Stadia Maps Management API

The Account Management API lets you manage properties, domains, and API keys programmatically rather than using the client dashboard. Most of our customers are well-served by the client dashboard, but can offer a programmatic account management API on request for certain use cases.

• Adding multiple domains per property
• Managing large numbers of properties or domains that would not be manageable by hand
• Creating or revoking API keys programmatically

Looking for a key to access maps and other APIs?

This page discusses tools for managing large numbers of web properties and apps at scale. If you're trying to get access to our map tiles, search, routing, or other products, head on over to our Authentication & Limits page instead.

Authentication

Our Management 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.

Note

Management API access is only available on request. You do not need management API access to use our services (if you're looking for a regular API key, head to our authentication docs.

If you would like access, please contact us at support@stadiamaps.com, and tell us about your use case. You will only be able to see your management API key after we enable access.

To find your Management API key, head over to your management panel and account details, and if you have Management 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/. We offer a web browsing mode so you can informally familiarize yourself with the layout of the API.

Base 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 period of usage for a property (as a list of Stat objects; see the stability note below)
• 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

Stats Result

An object representing one period of credit usage grouped by type, for a property or account.

Fields

Field Name	Field Type	Attributes	Description
data	Object[string, Object[ISO Date, Stat]]		a dictionary of stats, by type
start_date	ISO Date		the first date of the period for which data is returned
end_date	ISO Date		the last date of the period for which data is returned

Stat

An object representing one day of credit usage for a specific type of request.

Fields

Field Name	Field Type	Attributes	Description
value	integer		credit usage for this period

Notes:

• See our pricing page for a breakdown of how many credits each request kind costs.

Stability Note

We provide stats as a convenience, but note that we do not make any interface stability guarantees at this time.

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 *.
subdomain	string		a subdomain prepended to the base_domain, (e.g., www.)

Note: The wildcard and subdomain fields should be considered mutually 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
id	integer		the primary key for the Plan
name	string		a human-readable name
interval	string		the plan's billing interval (currently always month)
base_price	string		the base cost of a plan; amounts in currency (as a string decimal, e.g., "20.00")
additional_usage_price	string		the cost of 1000 additional credits for this plan; amounts in currency (as a string decimal, e.g., "0.02")
currency	string		the currency of a plan (in the form of USD or CHF; currently always USD)
included_credits	string		the number of credits covered by your plan's fixed fee every month

Note: requests above included_credits may be soft limited, hard limited, or charged as an overage depending on your plan and account settings.

Additional Documentation

Additional documentation may be found in the API itself by using OPTIONS or browsing it in a web browser.

OpenAPI

A reasonably complete OpenAPI specification exists at https://client.stadiamaps.com/api/v1/openapi/. 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 support@stadiamaps.com. We hope you don't find any, but please let us know if you do!