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!