Layers & tables API

The Layers and Tables API allows publishers to set, edit and update layers and tables.

Layers and tables list

GET /layers/

List layers and tables

List layers (at layers/) and tables (at tables/) respectively. List views follow the Catalog API semantics.

Response 200

Headers

Content-Type: application/json

Body

[{
    "id": 123,
    "url": "https://{domain}/services/api/v1/layers/123/",
    "type": "layer",
    "title": "Fictional Boundary Points",
    "first_published_at": "2013-01-01T00:01:01",
    "published_at": "2013-12-03T03:56:55Z"
}]

POST /layers/

Create a layer or table

All fields except name and data.datasources are optional.

Request

Headers

Content-Type: application/json

Body

{
    "title": "Fictional Boundary Points",
    "description": "These points are totally fictional!",
    "collected": "2013-01-01"
    "license": {
        "id": 3, 
        "title": "Creative Commons Attribution 3.0 New Zealand", 
        "type": 1, 
        "type_name": "Creative Commons license", 
        "url": "https://data-test.linz.govt.nz/services/api/v1/licenses/3/"
    },
    "supplier_reference": "TIVPAS",
    "version_reference": "added more data",
    "default_style_id": 3,

    "publish": true,
    "mapstream_id": 3,
    "categories": ["topographic/nz-topo-offshore-islands-data/terrain"],
    "tags": ["tag1", "tag2"],
    "permissions": "https://{domain}/services/api/v1/layers/123/permissions",
    "publish_to_catalog_services": true,
    "autoupdate": {
        "behavior": "yes-noschema",
        "schedule": "@weekly"
    }

    "data": {
        "datasources": [
            {
                "id": 345
            }
        ],
        "encoding": "utf-8",
        "crs": "EPSG:4326",
        "elevation_field": "Z",
        "primary_key_field": "id",

        "geometry_field":
            "GEOMETRY",
            "WKT",
            ["X", "Y"],
            null,
    },

    "tilegrids": []
}

Response 201

Headers

Content-Type: application/json
Location: https://{domain}/services/api/v1/layers/123/versions/789/

Body

{
    "title": "Fictional Boundary Points",
    "id": 123,
    "url": "https://{domain}/services/api/v1/layers/123/",
    "type": "layer",

    "collected_at": ["2013-01-01"],
    "created_at": "2013-01-01",
    "first_published_at": "2013-01-01",

    "description": "These points are totally fictional!",
    "description_html": "<p>These points are totally fictional!</p>",

    "group": {
        "id": 7,
        "name": "A group"
    },
    "data": {
        "encoding": null,
        "crs": "EPSG:4326",
        "crs_display": "WGS 84",
        "primary_key_fields": "GEOMETRY",
        "datasources": "https://{domain}/services/api/v1/layers/123/versions/456/datasources/",
        "datasource_count": 1,
        "geometry_field": "GEOMETRY",
        "geometry_type": "point",
        "fields": [{
            "type": "geometry",
            "name": "GEOMETRY"
        }, {
            "type": "integer",
            "name": "id"
        }, {
            "type": "double",
            "name": "spot_height"
        }],
        "feature_count": 200,
        "import_started_at": "2013-12-03T15:00:27.870364Z", 
        "import_ended_at": "2013-12-03T15:04:41.621934Z", 
        "import_log": {
            "invalid_geometries": 0, 
            "messages": 0
        },
        "change_summary": {
            "deleted": 0,
            "updated": 0,
            "inserted": 2,
            "schema_changes": {
                "added": [],
                "changed": [],
                "removed": [],
                "geometry_type_changed": false,
                "primary_keys_changed": false,
                "srid_changed": false
            }
        }, 
        "source_summary": {
            "paths": [
                "fictional_points.shp"
            ], 
            "filenames": [
                "fictional_points.zip"
            ], 
            "descriptions": [
                ""
            ], 
            "types": [
                "Upload"
            ], 
            "formats": [
                "Shapefile"
            ]
        },
        "sample": "https://{domain}/services/api/v1/layers/123/versions/456/data/sample/"
    },
    "url_html": "https://koordinates.com/layer/123-fictional-points/",
    "published_version": "https://{domain}/services/api/v1/layers/123/versions/456/",
    "latest_version": "https://{domain}/services/api/v1/layers/123/versions/456/",
    "this_version": "https://{domain}/services/api/v1/layers/123/versions/456/",
    "kind": "vector",
    "categories": [],
    "tags": [],
    "collected_at": null,
    "created_at": "2013-12-03T15:00:27.870",
    "license": null,
    "metadata": null,
    "publish_to_catalog_services": false,
    "permissions": "https://{domain}/services/api/v1/layers/123/permissions/",
    "autoupdate": {
        "behavior": "no",
        "schedule": null
    },
    "supplier_reference": "",
    "styles": "https://{domain}/services/api/v1/layers/123/styles/",
    "tilegrids": [],
    "default_style": null
}

Layers and table drafts

GET /layers/drafts/

List layers and tables drafts

A filterable list views of layers (layers/drafts/) and and tables (tables/drafts/) respectively, similar to /layers/ and /tables/. This view shows the draft version of each layer or table. If the most recent version of a layer or table has been published already, it won’t appear here.

All the same filters and ordering from layers/ and tables/ apply.

Response 200

Headers

Content-Type: application/json

Body

[{
    "id": 123,
    "url": "https://{domain}/services/api/v1/layers/123/",
    "type": "layer",
    "title": "Fictional Boundary Points",
    "first_published_at": "2013-01-01T00:01:01",
    "published_at": "2013-12-03T03:56:55Z"
}]

Layer and table detail

GET /layers/{id}/

Get a layer or table detail

Displays details of a layer layers/{id}/ or a table tables/{id}/. This view displays the published version only. To get the latest version, hit/layers/{id}/versions/latest/

Both of these URLs work for either layers or tables. This is because layers can be turned into tables and vice versa. If /tables/123/ is hit for a layer, or /layers/123/ for a table, the behaviour and response will be the same as the “correct” URL, except that the response will contain a Location header specifying the canonical URL. This applies to all sub-urls also (permissions/, metadata/, versions/, etc)

Response 200

Headers

Content-Type: application/json

Body

{
    "title": "Fictional Boundary Points",
    "id": 123,
    "url": "https://{domain}/services/api/v1/layers/123/",
    "type": "layer",

    "collected_at": ["2013-01-01"],
    "created_at": "2013-01-01",
    "first_published_at": "2013-01-01",

    "description": "These points are totally fictional!",
    "description_html": "<p>These points are totally fictional!</p>",

    "group": {
        "id": 7,
        "name": "A group"
    },
    "data": {
        "encoding": null,
        "crs": "EPSG:4326",
        "crs_display": "WGS 84",
        "primary_key_fields": "GEOMETRY",
        "datasources": "https://{domain}/services/api/v1/layers/123/versions/456/datasources/",
        "datasource_count": 1,
        "geometry_field": "GEOMETRY",
        "geometry_type": "point",
        "fields": [{
            "type": "geometry",
            "name": "GEOMETRY"
        }, {
            "type": "integer",
            "name": "id"
        }, {
            "type": "double",
            "name": "spot_height"
        }],
        "feature_count": 200,
        "import_started_at": "2013-12-03T15:00:27.870364Z", 
        "import_ended_at": "2013-12-03T15:04:41.621934Z", 
        "import_log": {
            "invalid_geometries": 0, 
            "messages": 0
        },
        "change_summary": {
            "deleted": 0,
            "updated": 0,
            "inserted": 2,
            "schema_changes": {
                "added": [],
                "changed": [],
                "removed": [],
                "geometry_type_changed": false,
                "primary_keys_changed": false,
                "srid_changed": false
            }
        }, 
        "source_summary": {
            "paths": [
                "fictional_points.shp"
            ], 
            "filenames": [
                "fictional_points.zip"
            ], 
            "descriptions": [
                ""
            ], 
            "types": [
                "Upload"
            ], 
            "formats": [
                "Shapefile"
            ]
        },
        "sample": "https://{domain}/services/api/v1/layers/123/versions/456/data/sample/"
    },
    "url_html": "https://koordinates.com/layer/123-fictional-points/",
    "published_version": "https://{domain}/services/api/v1/layers/123/versions/456/",
    "latest_version": "https://{domain}/services/api/v1/layers/123/versions/456/",
    "this_version": "https://{domain}/services/api/v1/layers/123/versions/456/",
    "kind": "vector",
    "categories": [],
    "tags": [],
    "collected_at": null,
    "created_at": "2013-12-03T15:00:27.870",
    "license": null,
    "metadata": null,
    "publish_to_catalog_services": false,
    "permissions": "https://{domain}/services/api/v1/layers/123/permissions/",
    "autoupdate": {
        "behavior": "no",
        "schedule": null
    },
    "supplier_reference": "",
    "styles": "https://{domain}/services/api/v1/layers/123/styles/",
    "tilegrids": [],
    "default_style": null
}

DELETE /layers/{id}/

Delete a layer or table

Deletes specified layer.

Response 204

Layer and table versions

GET /layers/{id}/versions/

List layer or table versions

Filterable list views of versions of a specific layer or table, always sorted newest to oldest.

Parameters

data__source_revision: number (optional). If the version’s source supports revisions, find versions using a specific revision. Values depend on the source type. Optionally use data__source_revision__lt ordata__source_revision__gte to filter using < or >= operators respectively.

Response 200

Headers

Content-Type: application/json

Body

[
    {
        "id": 456,
        "url": "https://{domain}/services/api/v1/layers/1/versions/7/"
        "created_at": "2013-03-01 00:00:01",
        "reference": "More data",
        "created_by": {
            "id": 3,
            "name": "Bob Jones"
        },
        "status": "importing",
        "progress": 0.5
    }
]

POST /layers/{id}/versions/

Create layer or table version

Creates a new draft version, accepting the same content as POST layers/. If anything in the data object has changed then an import will begin immediately. Otherwise to force a re-import from the previous sources call layers/{id}/versions/{version}/import/.

Request

Headers

Content-Type: application/json

Body

{
    "title": "Fictional Boundary Points",
    "description": "These points are totally fictional!",
    "collected": "2013-01-01"
    "license": {
        "id": 3, 
        "title": "Creative Commons Attribution 3.0 New Zealand", 
        "type": 1, 
        "type_name": "Creative Commons license", 
        "url": "https://data-test.linz.govt.nz/services/api/v1/licenses/3/"
    },
    "supplier_reference": "TIVPAS",
    "version_reference": "added more data",
    "default_style_id": 3,

    "publish": true,
    "user": {
        "id": 3, 
        "name": "Bob Jones"
    }, 
    "categories": ["topographic/nz-topo-offshore-islands-data/terrain"],
    "tags": ["tag1", "tag2"],
    "permissions": "https://{domain}/services/api/v1/layers/123/permissions/"
    "publish_to_catalog_services": true,
    "autoupdate": {
        "behavior": "yes-noschema",
        "schedule": "@weekly"
    }

    "data": {
        "datasources": [
            {
                "id": 345
            }
        ],
        "encoding": "utf-8",
        "crs": "EPSG:4326",
        "elevation_field": "Z",
        "primary_key_field": "id",

        "geometry_field":
            "GEOMETRY",
            "WKT",
            ["X", "Y"],
            null,
    },
    "tilegrids": [
        "EPSG:2193"
    ],
    "default_style": 10
}

Response 201

Headers

Content-Type: application/json
Location: https://{domain}/services/api/v1/layers/123/versions/789/

Body

{}

Response 409

Headers

Content-Type: application/json
Location: https://{domain}/services/api/v1/layers/123/versions/234/

Body

{"error": "There is already a draft version active for this layer."}

Layer or table version

GET /layers/{id}/versions/{id}/

Get layer or table version

Get the details for a specific layer or table version.

Response 200

Headers

Content-Type: application/json

Body

{
    "version": {
        "id": 456,
        "url": "https://{domain}/services/api/v1/layers/123/versions/456/"
        "created_at": "2013-03-01 00:00:01",
        "reference": "added more data",
        "created_by": {
            "id": 3,
            "name": "Bob Jones"
        },
        "status": "importing",
        "progress": 0.5,
    },

    "title": "Fictional Boundary Points",
    "id": 123,
    "url": "https://{domain}/services/api/v1/layers/123/",
    "type": "layer",

    "collected_at": ["2013-01-01"],
    "created_at": "2013-01-01",
    "first_published_at": "2013-01-01",

    "description": "These points are totally fictional!",
    "description_html": "<p>These points are totally fictional!</p>",

    "group": {
        "id": 7,
        "name": "A group"
    },
    "data": {
        "encoding": null,
        "crs": "EPSG:4326",
        "crs_display": "WGS 84",
        "primary_key_fields": "GEOMETRY",
        "datasources": "https://{domain}/services/api/v1/layers/123/versions/456/datasources/",
        "datasource_count": 1,
        "geometry_field": "GEOMETRY",
        "geometry_type": "point",
        "fields": [{
            "type": "geometry",
            "name": "GEOMETRY"
        }, {
            "type": "integer",
            "name": "id"
        }, {
            "type": "double",
            "name": "spot_height"
        }],
        "feature_count": 200,
        "import_started_at": "2013-12-03T15:00:27.870364Z", 
        "import_ended_at": "2013-12-03T15:04:41.621934Z", 
        "import_log": {
            "invalid_geometries": 0, 
            "messages": 0
        },
        "change_summary": {
            "deleted": 0,
            "updated": 0,
            "inserted": 2,
            "schema_changes": {
                "added": [],
                "changed": [],
                "removed": [],
                "geometry_type_changed": false,
                "primary_keys_changed": false,
                "srid_changed": false
            }
        }, 
        "source_summary": {
            "paths": [
                "fictional_points.shp"
            ], 
            "filenames": [
                "fictional_points.zip"
            ], 
            "descriptions": [
                ""
            ], 
            "types": [
                "Upload"
            ], 
            "formats": [
                "Shapefile"
            ]
        },
        "sample": "https://{domain}/services/api/v1/layers/123/versions/456/data/sample/"
    },
    "url_html": "https://koordinates.com/layer/123-fictional-points/",
    "published_version": "https://{domain}/services/api/v1/layers/123/versions/456/",
    "latest_version": "https://{domain}/services/api/v1/layers/123/versions/456/",
    "this_version": "https://{domain}/services/api/v1/layers/123/versions/456/",
    "kind": "vector",
    "categories": [],
    "tags": [],
    "collected_at": null,
    "created_at": "2013-12-03T15:00:27.870",
    "license": null,
    "metadata": null,
    "publish_to_catalog_services": false,
    "permissions": "https://{domain}/services/api/v1/layers/123/permissions/",
    "autoupdate": {
        "behavior": "no",
        "schedule": null
    },
    "supplier_reference": "",
    "tilegrids": [],
    "default_style": null
}

PUT /layers/{id}/versions/{id}/

Edit layer or table version

Edits this draft layer version. If the layer is already published, a 405 response will be returned. Accepts same fields as GET above, but ignores the version object. If there is anything in the data object, cancel any existing import and start a new one.

Response 200

Headers

Content-Type: application/json

Body

{
    "version": {
        "id": 456,
        "url": "https://{domain}/services/api/v1/layers/123/versions/456/"
        "created_at": "2013-03-01 00:00:01",
        "reference": "added more data",
        "created_by": {
            "id": 3,
            "name": "Bob Jones"
        },
        "status": "importing",
        "progress": 0.5
    },

    "title": "Fictional Boundary Points",
    "id": 123,
    "url": "https://{domain}/services/api/v1/layers/123/",
    "type": "layer",

    "collected_at": ["2013-01-01"],
    "created_at": "2013-01-01",
    "first_published_at": "2013-01-01",

    "description": "These points are totally fictional!",
    "description_html": "<p>These points are totally fictional!</p>",

    "group": {
        "id": 7,
        "name": "A group"
    },
    "data": {
        "encoding": null,
        "crs": "EPSG:4326",
        "crs_display": "WGS 84",
        "primary_key_fields": "GEOMETRY",
        "datasources": "https://{domain}/services/api/v1/layers/123/versions/456/datasources/",
        "datasource_count": 1,
        "geometry_field": "GEOMETRY",
        "geometry_type": "point",
        "fields": [{
            "type": "geometry",
            "name": "GEOMETRY"
        }, {
            "type": "integer",
            "name": "id"
        }, {
            "type": "double",
            "name": "spot_height"
        }],
        "feature_count": 200,
        "import_started_at": "2013-12-03T15:00:27.870364Z", 
        "import_ended_at": "2013-12-03T15:04:41.621934Z", 
        "import_log": {
            "invalid_geometries": 0, 
            "messages": 0
        },
        "change_summary": {
            "deleted": 0,
            "updated": 0,
            "inserted": 2,
            "schema_changes": {
                "added": [],
                "changed": [],
                "removed": [],
                "geometry_type_changed": false,
                "primary_keys_changed": false,
                "srid_changed": false
            }
        }, 
        "source_summary": {
            "paths": [
                "fictional_points.shp"
            ], 
            "filenames": [
                "fictional_points.zip"
            ], 
            "descriptions": [
                ""
            ], 
            "types": [
                "Upload"
            ], 
            "formats": [
                "Shapefile"
            ]
        },
        "sample": "https://{domain}/services/api/v1/layers/123/versions/456/data/sample/"
    },
    "url_html": "https://koordinates.com/layer/123-fictional-points/",
    "published_version": "https://{domain}/services/api/v1/layers/123/versions/456/",
    "latest_version": "https://{domain}/services/api/v1/layers/123/versions/456/",
    "this_version": "https://{domain}/services/api/v1/layers/123/versions/456/",
    "kind": "vector",
    "categories": [],
    "tags": [],
    "collected_at": null,
    "created_at": "2013-12-03T15:00:27.870",
    "license": null,
    "metadata": null,
    "publish_to_catalog_services": false,
    "permissions": "https://{domain}/services/api/v1/layers/123/permissions/",
    "autoupdate": {
        "behavior": "no",
        "schedule": null
    },
    "supplier_reference": "",
    "tilegrids": [],
    "default_style": null
}

Response 405

Headers

Content-Type: application/json

Body

{"error": "This version isn't a draft."}

DELETE /layers/{id}/versions/{id}/

Delete layer or table version

Deletes this draft version (revert to published).

Response 204

Response 405

Headers

Content-Type: application/json

Body

{"error": "This version isn't a draft."}

Response 409

Headers

Content-Type: application/json

Body

{"error": "This version is already deleted."}

Layer or table import

POST /layers/{id}/versions/{version}/import/

Start layer or table data import

Starts importing this draft layer version (cancelling any running import), even if the data object hasn’t changed from the previous version.

No POST data.

Response 202

Headers

Location: https://{domain}/services/api/v1/layers/123/versions/789/

Response 409

Headers

Content-Type: application/json

Body

{"error": "This version isn't a draft."}

Layer or table create and import

POST /layers/{id}/versions/{version}/publish/

Publish layer or table version

Creates a publish task just for this version, which publishes as soon as any import is complete.

No POST data.

Response 201

Headers

Location: https://{domain}/services/api/v1/publish/456/

Body

# this change didn't require a reimport. The publish has taken place

Response 202

Headers

Location: https://{domain}/services/api/v1/publish/456/

Body

# reimport required. The publish task has been created but is not yet finished

Response409

Headers

Content-Type: application/json

Body

{"error": "This version is already published."}

Response 409

Headers

Content-Type: application/json
Location: https://{domain}/services/api/v1/publish/456/

Body

{"error": "This version isn't published yet, but already has a publish job"}

Site Admin APIs

Layers & tables API

Layers and tables list

Layers and table drafts

Layer and table detail

Layer and table versions

Parameters

Layer or table version

Layer or table import

Layer or table create and import