Export API

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

Export List

GET /exports/

Lists Exports

Returns a list of exports you've created.

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/exports/1/",
        "download_url": "https://{domain}/services/api/v1/exports/1/download/"
    }
]

An export can have one of five statuses:

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. The coordinate reference system in the form EPSG:XXXX where XXXX is the identifier. For more info on EPSG, refer to http://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 tile_id 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: 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.

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/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. Defaults to 1 (no change), maximum of 16.