Export API

The Export API can be used to create and download exports of data.

For the full reference, see Exports on apidocs.koordinates.com.

Export list

GET/exports/Lists Exports

Returns a list of exports. You see your own exports; site admins see every export on the site. The list supports page, page_size and sort (name, -name, created_at, -created_at; newest first by default), and these filters: state, created_via (web, api, app), user (a user ID), created_at, delivery_method and from (a site domain, which must be sent with user). Send the header Expand: list for the full detail of each export. Your key needs the exports:read scope.

Response 200

Content-Type: application/json

Body

[
    {
        "id": 1,
        "name": "example-layer-SHP",
        "created_at": "2017-04-02T15:20:20.237129Z",
        "created_via": "api",
        "state": "complete",
        "url": "https://{domain}/services/api/v1.x/exports/1/",
        "download_url": "https://{domain}/services/api/v1.x/exports/1/download/"
    }
]

An export can have one of five states:

processing: the export is being created and will be available for download soon. If the export is processing, the download_url will be null.
cancelled: the export was processing but has been cancelled before it was completed.
error: there was an error during the creation of the export.
complete: the export has finished processing and is available for download at the location provided in download_url.
gone: the export was completed successfully but has since been removed or has expired from the system.

POST/exports/Create an Export

To create and start a new export, post to this view.

Parameters

crs: string (required; validation returns missing-crs without it). The coordinate reference system in the form EPSG:XXXX where XXXX is the identifier. For more info on EPSG, refer to epsg.io. Please note that KML exports can only be exported in WGS84 / EPSG:4326.
formats: object (required). An object keyed by layer or table “kind” (see Layers & tables API kind property) with the mimetype of the format you want in the download. For example: application/x-zipped-shp for vector data. You must have one entry for each data kind you are exporting.
items: array (required). A list of Layer or Table items to export. Each entry in the list is an object with the key item with value of the item’s API URL. The entry can also have an optional field color (for export formats that support it, a 7 character RGB value, e.g. #3399DD) or tiles, a list of tile IDs for exporting specific tiles from tiled datasets.
name: string (optional). The name for the archive. If not provided this will be generated from the content.
extent: object or string (optional). A Crop Feature or Geometry extent for cropping to a specific geographic area. See advanced options below.
options: object (optional). Additional format options. See below for more information.

Example

{
    "name": "my-export",
    "crs": "EPSG:2193",
    "formats": {"vector": "application/x-zipped-shp"},
    "items": [
        {"item": "https://{domain}/services/api/v1.x/layers/LAYER_ID/"}
    ],
    "extent": {
        "type": "Polygon",
        "coordinates": [[[174.75, -36.88], [174.75, -36.84], [174.79, -36.84], [174.79, -36.88], [174.75, -36.88]]]
    }
}

The response is 201 with the export in the processing state and a Location header for the export. Exports are also gated by your site’s API export setting, so a site that hasn’t enabled API exports refuses them.

Discovering format types

Format types can be discovered via an OPTIONS request to the Export List API. The available format types will depend on the capabilities and options of the Koordinates site.

Defining a crop extent

Layer data in exports can be cropped to a particular geographic area by providing an extent. There are two ways to define an extent for cropping:

By Geometry

A valid GeoJSON polygon or multi-polygon geometry object, for example:

{
    // …
    "extent": {
        "type": "Polygon",
        "coordinates": [
            [
                [170.694580078125, -43.229195113965],
                [170.694580078125, -42.5854442573849],
                [172.177734375, -42.5854442573849],
                [172.177734375, -43.229195113965],
                [170.694580078125, -43.229195113965]
            ]
        ]
    }
    // …
}

For performance reasons, the overall complexity of the geometry is limited to no more than 1,000 vertices.

Note that the coordinates must be in WGS84 / EPSG:4326 projection. If a CRS is provided it will be ignored.

By Crop Feature

A Koordinates site might have pre-defined cropping layers and features configured. If so, these can be used to crop to pre-defined areas. Crop Layers and Crop Features can be discovered with the Crop Layers API. Providing a Crop Feature URL as the extent will set the geometry of that feature as the cropping geometry for the export.

{
    // …
    "extent": "https://{domain}/services/api/v1.x/exports/croplayers/1/cropfeatures/1/"
    // …
}

Additional options

The options object can include additional information:

page_size string: PDF only - page size. Either a4 (default), a3 or letter.
page_orientation string: PDF only - page orientation. Either landscape (default) or portrait.
include_scale boolean: PDF only - should the map include a scale bar. Defaults to false.
include_scale_grid boolean: PDF only - should the map include a scale grid. Defaults to false.
include_lat_lon_grid boolean: PDF only - should the map include graticules. Defaults to false.
include_legend boolean: PDF only - should the map include a legend. Defaults to false.
pdf_raster_dpi integer: PDF only - the raster DPI included in the map. Defaults to 72.
raster_resolution_multiplier integer: Downsampling multiplier for raster formats: 1 (default, no change), 2 or 4. In the v1.x API, set this on each entry in items instead of in options.

Export detail and download

GET/exports/{id}/Get an export

Returns the export with its items, crs, extent, formats, options, is_cropped, progress, and the zipped and unzipped sizes. Poll it until state is complete.

GET/exports/{id}/download/Download an export

Redirects to a signed URL for the export file. The signed URL doesn’t accept an Authorization header, so don’t forward your key when you follow the redirect to a different host.

A completed export can’t be deleted: DELETE /exports/{id}/ returns 409.

Validate an export

POST/exports/validate/Validate an export

Post the same body you’d send to create an export. Koordinates checks whether it’s valid and estimates its size, without creating the export. An invalid body returns 400 with the field errors, for example {"errors": {"formats": {"vector": ["\"x/y\" is not a valid choice."]}}, "status_code": 400}.

Response 200

Body

{
    "items": [
        {
            "item": "https://{domain}/services/api/v1.x/layers/{layer-id}/",
            "color": "#003399",
            "license": null,
            "price": "0.00",
            "currency": null,
            "is_valid": true,
            "invalid_reasons": [],
            "size_estimate_zipped": 1234567
        }
    ],
    "size_estimate_zipped": 1234567,
    "is_valid": true,
    "invalid_reasons": [],
    "suggested_crs": [
        {
            "id": "EPSG:26767",
            "url": "https://{domain}/services/api/v1.x/coordinate-systems/EPSG:26767/",
            "srid": 26767,
            "name": "NAD27 / Georgia West",
            "kind": "projected",
            "units": "US survey foot",
            "url_external": "https://epsg.io/26767"
        }
        // …
    ]
}