Koordinates API Documentation (1.0.1)

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/

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.

Pagination

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

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.

The Export API provides methods for extracting data in bulk from the Koordinates platform. Multiple layers can be exported in one download, data can be cropped, reprojected into different coordinate reference systems, and data can be exported in many different formats.

The Raster Query API allows users to request information related to a point location from one or more Koordinates grid or raster datasets.

URL

Your URL endpoint is dependent on the particular Koordinates service you wish to access.

The URL for the Koordinates.com will be: https://koordinates.com/services/query/v1/raster

The raster query API returns in JSON:

content-type: application/vnd.koordinates.rasterQuery+json Formats can be specified via URL. For example: https://koordinates.com/services/query/v1/raster.json

They can also be specified using the HTTP Accept header with the appropriate content-type against the base URL. For example: application/vnd.koordinates.rasterQuery.1+json.

By default, all responses use the newest format. While we try very hard to prevent backwards-incompatible breaks, please note that it may happen in future.

If you're using the URL endpoint (for example, rasterQuery.json) you can pass a &v=1 parameter to specify version 1. Note that the current version is 1.

Compression

Add a request header with Accept-Encoding: gzip to get compressed results. This dramatically reduces the size of the response and will speed up your API requests.

The Vector Query API allows users to request information related to a point location from one or more Koordinates vector datasets.

URL

Your URL endpoint is dependent on the particular Koordinates service you wish to access.

The URL for Koordinates.com site will be: https://koordinates.com/services/query/v1/vector

Formats

The vector query API returns in:

• JSON: content-type: application/vnd.koordinates.setQuery+json. Results are encoded as GeoJSON-compatible Feature objects.
• Xml: content-type: application/vnd.koordinates.vectorQuery+xml. A schema is available. Geometries are encoded as GML v3 geometry objects.
• Json-gmaps: content-type: application/vnd.koordinates.vectorQuery-gmaps+json. For use with the Google Maps API, geometries are returned as arrays of geometry objects, with linestrings & polygons encoded for faster display & smaller response-size.

Formats can be specified via URL. For example: https://koordinates.com/services/query/v1/vector.json

They can also be specified using the HTTP Accept header with the appropriate content-type against the base URL. For example: application/vnd.koordinates.vectorQuery.1+json

By default, all responses use the newest format. While we try very hard to prevent backwards-incompatible breaks, please note that it may happen in future

If you're using the URL endpoint (eg. vector.json) you can pass a &v=1 parameter to specify version 1.0. The current version is 1.1.

Compression

Add a request header with Accept-Encoding: gzip to get compressed results. This dramatically reduces the size of the response and will speed up your API requests.

The following APIs are used to connect to external services, import and manage publication of data on the Koordinates platform.

Concepts

Sources, Data Sources and Scans

A Source is a container of data that we can potentially process. Examples of Sources include:

• An uploaded Zip containing many pieces of data
• An internet-accessible WFS server or Esri AGOL service account
• A connected S3 bucket

A Data Source is a specific file, service or resource in a Source that could be ingested into the Koordinates platform. Some examples of data sources include:

• A particular shapefile in an uploaded Zip
• A specific layer in a WFS (Web Feature Service) or Esri AGOL account
• A single GeoTIFF in an AWS S3 bucket

Data sources are discovered by Koordinates by running a Scan. This is a process where we inspect the source to find the available data sources, and make them availale for importing. Some sources, like an upload, only need to be scanned once. Other sources, like an S3 bucket, can be regularly scanned to find new, updated or removed data sources.

Importing Data

Data sources are used to create Layers, Tables and Documents. This is typically done by creating a new object and providing refences to the data sources discovereed in a scan.

• Layers and Tables can be created from one or more data sources. If more than one data source is used they must be of the same data type (e.g. vector polyon, geotiff, etc) and have the same schema (columns, field types, number of bands, etc).

• Documents can only be created form a single data source and only if its a file-like datasource.

• Sets are created from other Layers and Tables, rather than from data sources.

Versions and Publishing

Layers, Tables, Documents and Sets are versioned.

• The published version is the currently visible version to users. Exports of the item will include data from the published version. Published versions cannot be edited. To modify an item, a new draft version is created.
• The draft version, if it exists, can be modified. New data can also be imported to the draft version. Once edits to the draft are complete the draft can be published.

The Data Sources API provides read and write access to sources, datasources and scans.

Source-specific notes

There are several types of sources. Each exposes the same set of core fields, but some fields are only exposed or accepted for specific types of sources. Everything in options is optional.

CIFS, URL, ArcGIS, and WFS source options

All these source types can accept credentials in an options field:

• options:
  • username : username to access this server.
  • password : password for this server.
  • ssl_verify : A boolean specifying whether Koordinates should verify the SSL certificate of the host when scanning this source. Defaults to true. Username and password are write-only. They are never returned to clients via the API.

ArcGIS Server

• url_remote : The URL of your ArcGIS server, usually ending with/rest/api/services/. Must not contain credentials.

• options : In addition to the options listed above, ArcGIS also accepts:

  • folders : A JSON array of folders to scan. If not given, the whole server will be scanned.

CIFS

• url_remote : A URL of the form "cifs://host/sharename", optionally with extra path segments. Must not contain credentials.

PostgreSQL

• url_remote : A URL of the form "postgresql://host:port/database". Must not contain credentials.

• options :

  • username : username to access the PostgreSQL database.
  • password : postgres database password.
  • schemas : A JSON array containing schema names, e.g.: "schemas": ["public", "other_schema"]

URL

A URL source defines an FTP, HTTP or HTTPS url to an archive Koordinates can scan for data.

Currently accepts these archives:

• .zip
• .tar.gz, .tgz
• .7z

URL sources accept the following extra fields:

• url_remote : The URL to download the archive. Must not contain credentials.

WFS Server

• url_remote : The URL to the WFS server endpoint. Must not contain credentials.

Layer APIs