Introducing the Admin API

For the full reference to every endpoint, see apidocs.koordinates.com.

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. Some URLs without one are also served, but only the form with the trailing slash is supported.

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

The API is served under both /services/api/v1.x/ and /services/api/v1/. The API reference uses v1.x.

Python client library

An API client is a convenient way to start building your integration with the Koordinates API. Koordinates publishes an official Python client library under an open source licence. It handles much of the code for scripting read and write operations against the API, which makes it easier to manage your Koordinates site. See the Koordinates Python Client Library documentation and its source code on GitHub.

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 on the API Keys page (/my/api/), which you open from your user menu on the website. See Set scopes for an API token.

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 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.x/layers/4/",
    "type": "layer",
    "name": "Road Centerlines",
    "permissions": "https://{domain}/services/api/v1.x/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.

Responses also include an OAuth-Scopes header listing the scopes your token or API key has. A request that needs a scope your key lacks returns 401 with an error such as Invalid API key scope: requires 'viewers:read'.

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

Request a page with page and set its size with page_size. Some list and search views will provide a Link header that provides a list of related links to the current view, with rel values such as page-next, page-previous and page-last for pages, and sort-name, sort-name-desc or sort-recently-added for the sort options the view supports (for example ?sort=name). Pass the sort value from those links as the sort query parameter.

Errors

Error responses are JSON objects with an errors object and the status_code. Validation errors list each field with its messages, for example:

{
    "errors": {
        "title": ["This field is required."]
    },
    "status_code": 400
}

Other errors use a detail message ({"errors": {"detail": "Not found."}, "status_code": 404}). A few views, such as the Publishing API and the draft version conflicts in the Layers & tables API, return a single key that names the problem, for example {"already-exists": "…"}.

Dates and 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.