Koordinates API Documentation (1.0.1)

Documentation for Koordinates REST APIs.

Introduction

Koordinates provides a RESTful API that uses standard HTTP methods and status codes. This documentation provides detailed developer documentation for specific API endpoints, including request and response formats. This should be read in conjunction with the Help documentation available at https://help.koordinates.com/

Authentication

There are a number of ways to authenticate with the Koordinates API depending on your requirements. Note that not every method is available for every endpoint. Supported authentication methods are listed under in endpoint's "Authorization" section. Refer to API Tokens documentation for creating and modifying tokens. Most endpoints require the API token to carry a particular scope. Every response includes an Accepted-OAuth-Scopes header naming the scope the endpoint requires (* if none), and requests authenticated with a token also get an OAuth-Scopes header listing the scopes that token holds. A token lacking the required scope gets a 401 whose detail names the missing scope.

API Features

Pagination

List APIs are paginated with two query parameters:

• page - the page to return, 1-based. Defaults to 1.
• page_size - the number of items per page. Defaults to 100. Most endpoints cap it at 200; the group, license, version-datasource, version-tile and datasource link-resolution lists allow up to 100000. Asking for more than the cap is a 400.

List API responses will include pagination headers.

• X-Paginate-By - the number of items per page
• X-Resource-Range - the range of items in the current response in the form start-end/total

For example:

X-Paginate-By: 20
X-Resource-Range: 20-40/320

Searching and filtering

Search-backed list APIs - /data/, /layers/, /tables/, /items/ and /sources/ - share one set of query parameters, documented on /data/. Filters that take several values are repeated (?tag=a&tag=b) and OR-ed together; different filters are AND-ed. q is a free-text search over each item's title, description, tags, category and geotag names, plus its publisher's name, its field names and (for sets) its member layers. An item matches if it matches any term; items matching more terms rank higher, and title matches are weighted most heavily. With q and no sort, results are ordered by relevance. Query parameters the endpoint does not recognise are ignored rather than rejected, so a misspelt filter returns an unfiltered list. Recognised parameters with invalid values are a 400.

Faceting

Search-backed list APIs - the ones that accept q and a sort order, such as /data/, /layers/, /items/, /sources/ and /groups/ - also accept facets=true. This replaces the result list with the facet counts for the filters already applied, so a client can show how many results each remaining choice would return. Which facets come back depends on what the matching objects populate; possible keys are tag, group, geotag, category, license, raster_resolution, raster_band and point_cloud_contents. Each entry carries the value to filter by (key) and the number of results it would return (total). For example:

GET /services/api/v1.x/data/?kind=layer&facets=true

{
  "geotag": [
    {
      "key": "global/oceania/new-zealand",
      "name": "New Zealand",
      "total": 4021,
      "has_children": true,
      "geom": null
    },
    ...
  ],
  "category": [
    {"key": "cadastral", "name": "Cadastral", "total": 812},
    ...
  ]
}

Facet counts always cover the whole result set, whatever page and page_size say. Add geotag.geometry=true to include the selected geotag's geometry in the geotag facets.

Link Headers

List APIs that can be sorted or paged will usually include Link headers that conform to the RFC 5988 standard. For example:

Link:
  <https://{domain}/services/api/v1.x/layers/?page=2&page_size=20>; rel="page-next",
  <https://{domain}/services/api/v1.x/layers/?page=724&page_size=20>; rel="page-last",
  <https://{domain}/services/api/v1.x/layers/?page_size=20&sort=name>; rel="sort-name",
  <https://{domain}/services/api/v1.x/layers/?page_size=20&sort=-name>; rel="sort-name-desc",
  <https://{domain}/services/api/v1.x/layers/?page_size=20&sort=popularity>; rel="sort-most-popular",
  <https://{domain}/services/api/v1.x/layers/?page_size=20&sort=created_at>; rel="sort-recently-added",
  <https://{domain}/services/api/v1.x/layers/?page_size=20&sort=updated_at>; rel="sort-recently-updated",
  <https://{domain}/services/api/v1.x/layers/?page_size=20&sort=featured_at>; rel="sort-recently-featured",
  <https://{domain}/services/api/v1.x/layers/?page_size=20&sort=-featured_at>; rel="sort-recently-featured-oldest-first"

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