Stadia Maps Management API¶

The Management API is designed to allow our customers to manage their properties, domains, and API keys without having to visit the client dashboard in a web browser. 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.

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.

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/.

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)
• 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

Stats Result¶

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

Fields

Stat¶

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

Fields

Notes:

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

Domain¶

Domains allow access to our services via an authorized domain name.

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.

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.

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!