Unless indicated, the Koordinates Data Admin API is primarily a JSON API and we expect that you supply a Content-Type: application/json header with all requests.

All request URLs should end with a trailing slash. URLs without trailing slashes will be redirected to the correct path with a 301 Moved Permanently redirection response.

Note that, when documenting a resource, we use curly braces for identifiers. For example, we use {domain} when talking about the URL for your Koordinates warehouse:

https://{domain}/services/api/v1/data/

Python Client Library

An API client provides a convenient way to get started building your integration with the Koordinates API. At the current time, Koordinates supports an official Python reference implementation. Access the documentation for the Koordinates Python Client Library here.

We welcome contributions. If you've created a Koordinates API client library and you want to list it here, please get in touch.

Security and authentication

This is an SSL-only API and must be accessed using credentials of a valid, unlocked user account.

Access to the API is via Token Header Authentication. A token is identified by a 32-character key that is supplied in all API requests via the Authorization header, and has the form key {token_key}.

For example:

Authorization: key f91578f91325d5703cbfc61992571bc9

API tokens require specific scopes to access Koordinates APIs. You can create tokens and set their scopes at the 'APIs and Web Services' page under your user menu on the website.

The API is also accessible in a browser session using our browsable API explorer. First log in to your Koordinates Warehouse then navigate to any of the API endpoints to get a rendered view of the API. This is useful for testing and experimentation and is not suitable for client integrations.

Rate Limiting

The Koordinates Data Administration API is subject to “reasonable use” rate limiting. If you exceed our rate limits you will see receive a response with status code 429 - Too Many Requests. The Retry-After response header will specify the number of seconds we recommend you wait before attempting to access the API again.

Expansions

Expansions (sometimes known as “side-loads”) provide a way to include related content into a particular API view. For many property values, we supply a URL to the resource. For example:

{
    "id": 4, 
    "url": "https://{domain}/services/api/v1/layers/1/", 
    "type": "layer", 
    "name": "Road Centerlines", 
    "permissions": "https://{domain}/services/api/v1/layers/4/permissions/",
    ...

The permissions property points to a URL where we can see the permissions for this layer. We can include the permissions response directly in this request by including an Expand header with the value permissions.

Expand: permissions

More than one expansion can be requested by providing property names separated by commas.

A list of available expansions for any particular view is accessible via an OPTIONS request. This will return a JSON object that contains the key expansions and an array of valid expansion options. For example:

{
    "name": "Layer Detail", 
    "expansions": [
        "permissions"
    ]
}

Some list views can provide more detailed responses via the special list expansion. Note that list expansions cannot be used in conjunction with detailed item expansions.

OAuth Token Headers

When using token authentication, your key requires particular scopes to access the view. Every view that is provided via token authentication will have an Accepted-OAuth-Scopes header that specifies the scope required to use that view.

If you are authenticated with an OAuth token, responses will also include a OAuth-Scopes header that provides a list of scopes that the token can access.

List View Headers

API requests that return lists will supply headers related to the current page size and position. X-Paginate-By will provide the current number of records (maximum) displayed per page of results. X-Resource-Range provides a value in the form of “start-end/total” where the range is a 0-based index with exclusive upper bound. For example, “0-20/55” means your response includes the first 20 records out of 55. Page 2 of the same result set will have the range “20-40/55”.

Some list and search views will provide a Link header that provides a list of related links to the current view. This could include ‘next’, ‘previous’ and ‘last’ pages of a list view, alternative sorting options and more.

Dates & Times

Dates and times will be returned as ISO 8601 strings in UTC. You can supply ISO 8601 date times with timezones and they will be handled correctly. In the absence of time zone data, UTC will be assumed.

Description Fields

Many objects have a description field that accepts free-form text. This will be processed as Markdown and returned in a read-only description_html field.

Searching for Data

The Catalog API is the primary way to find data.