Skip to content
Help

Sets API

The Sets API can be used to make groups of layers, tables and documents.

Set list

Section titled “Set list”
GET/sets/Lists sets

Returns a paginated list of the sets available to you. Use page, page_size (maximum 200) and q to page and search, and sort to order the results.

The list is a summary of each set; to see its items, description and other detail, get the set detail.

Response 200

Headers

Content-Type: application/json
X-Resource-Range: 0-1/1

Body

[{
    "id": 1,
    "title": "My collection",
    "url": "https://{domain}/services/api/v1.x/sets/1/",
    "type": "set",
    "created_at": "2012-12-19T23:13:26.324Z",
    "thumbnail_url": "https://tiles-cdn.koordinates.com/services/tiles/v4/thumbnail/set=1.1,style=auto/1200x630.png",
    "kind": "geographic",
    "item_count": 2,
    "featured_at": null,
    "published_at": "2012-12-19T23:13:28.403Z",
    "first_published_at": "2012-12-19T23:13:28.403Z",
    "user_capabilities": ["can-star", "can-manage", "can-view-reports"],
    "user_permissions": ["find", "view", "admin"],
    "is_starred": false,
    "public_access": null
}]
POST/sets/Create a set

Required fields are:

  • Title
  • Description
  • Either group or user: the ID of the group or user to own the set. Some sites only allow groups to own data, and reject user with Only groups can own this object.

Other notable fields:

  • items: A list of layers, tables and/or documents specified using their URLs. The order of this list will be used when rendering.

A new set starts as an unpublished draft (published_version is null). Publish it with Publish set version to make it visible in the catalogue.

Request

Headers

Content-Type: application/json

Body

{
    "title": "a collection",
    "description": "My favourite layers",
    "categories": [],
    "tags": [],
    "group": 3,
    "items": [
        "https://{domain}/services/api/v1.x/layers/2/",
        "https://{domain}/services/api/v1.x/layers/1/"
    ]
}

Response 201

The response is the same set detail as Get a set detail, including the version fields shown in Set version (abridged here).

Headers

Content-Type: application/json
Location: https://{domain}/services/api/v1.x/sets/123/

Body

{
    "id": 123,
    "title": "a collection",
    "description": "My favourite layers",
    "description_html": "<p>My favourite layers</p>",
    "categories": [],
    "tags": [],
    "group": {
        "id": 3,
        "url": "https://{domain}/services/api/v1.x/groups/3/",
        "name": "My group",
        "country": "NZ"
    },
    "items": [
        "https://{domain}/services/api/v1.x/layers/2/",
        "https://{domain}/services/api/v1.x/layers/1/"
    ],
    "url": "https://{domain}/services/api/v1.x/sets/123/",
    "url_html": "https://{domain}/set/123-a-collection/",
    "metadata": null,
    "publish_to_catalog_services": false,
    "permissions": "https://{domain}/services/api/v1.x/sets/123/permissions/",
    "created_at": "2015-05-12T21:54:21.276Z"
}

Set drafts

Section titled “Set drafts”
GET/sets/drafts/List sets in draft state

A filterable list views of set drafts, similar to /sets/. This view shows the draft version of each set. If the most recent version of a set has been published already, it won’t appear here.

All the same filters and ordering from sets/ apply.

Response 200

Body

[
    {
        "id": 3,
        "title": "Brand New Set",
        "url": "https://{domain}/services/api/v1.x/sets/3/",
        "type": "set",
        "created_at": "2020-05-19T04:25:07.220568Z"
    },
    {
        "id": 4,
        "title": "Other New Set",
        "url": "https://{domain}/services/api/v1.x/sets/4/",
        "type": "set",
        "created_at": "2020-05-19T04:25:07.220568Z"
    }
]

Set detail

Section titled “Set detail”
GET/sets/{id}/Get a set detail

This view displays the published version of a set. To get the draft version, hit /sets/{id}/versions/draft/

Response 200

Body

{
    "id": 1,
    "title": "My collection",
    "description": "a collection of layers",
    "description_html": "<p>a collection of layers</p>",
    "categories": [],
    "tags": [],
    "group": {
        "id": 3,
        "url": "https://{domain}/services/api/v1.x/groups/3/",
        "name": "My group",
        "country": "NZ"
    },
    "items": [
        "https://{domain}/services/api/v1.x/layers/2/",
        "https://{domain}/services/api/v1.x/layers/1/"
    ],
    "url": "https://{domain}/services/api/v1.x/sets/1/",
    "url_html": "https://{domain}/set/1-a-collection/",
    "metadata": null,
    "publish_to_catalog_services": true,
    "permissions": "https://{domain}/services/api/v1.x/sets/1/permissions/",
    "created_at": "2012-12-19T23:13:26.324Z"
}

Set versions

Section titled “Set versions”
GET/sets/{id}/versions/List set versions

Filterable list views of versions of a specific set, always sorted newest to oldest.

Response 200

Body

[
    {
        "id": 2,
        "url": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
        "created_at": "2020-05-19T04:25:07.390291Z"
    }
]
POST/sets/{id}/versions/Create a set version

Creates a new draft version of a set. The request body is optional: the draft starts as a copy of the latest version, and any fields you send (the same as POST /sets/) are applied to it.

Response 201

Headers

Content-Type: application/json
Location: https://{domain}/services/api/v1.x/sets/1/versions/2/

Body: the full set version, as in Set version.

{
    "id": 2,
    "title": "a collection",
    "url": "https://{domain}/services/api/v1.x/sets/2/",
    "type": "set",
    "created_at": "2020-05-19T04:25:07.220568Z",
    "thumbnail_url": "",
    "description": "My favourite layers",
    "description_html": "<p>My favourite layers</p>",
    "latest_version": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
    "published_version": null,
    "this_version": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
    "categories": [],
    "tags": [],
    "group": {
        "id": 3,
        "url": "https://{domain}/services/api/v1.x/groups/3/",
        "name": "My group",
        "country": "NZ"
    },
    "url_html": "https://{domain}/set/2/",
    "metadata": null,
    "publish_to_catalog_services": false,
    "active_publish": null,
    "permissions": "https://{domain}/services/api/v1.x/sets/2/permissions/",
    "settings": {
        "lock_title_to_metadata": false,
        "lock_description_to_metadata": false,
        "lock_tags_to_metadata": false
    },
    "items": [
        "https://{domain}/services/api/v1.x/layers/2/",
        "https://{domain}/services/api/v1.x/layers/1/"
    ],
    "version": {
        "id": 2,
        "url": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
        "created_at": "2020-05-19T04:25:07.390291Z"
    }
}

Response 409

Headers

Content-Type: application/json
Location: https://{domain}/services/api/v1.x/sets/1/versions/2/

Body

{"already-exists": "This set already has a draft version"}

Set version

Section titled “Set version”
GET/sets/{id}/versions/{version}/Get set version

Get the details for a specific set version.

Response 200

Body

{
    "id": 2,
    "title": "a collection",
    "url": "https://{domain}/services/api/v1.x/sets/2/",
    "type": "set",
    "created_at": "2020-05-19T04:25:07.220568Z",
    "thumbnail_url": "",
    "description": "My favourite layers",
    "description_html": "<p>My favourite layers</p>",
    "latest_version": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
    "published_version": null,
    "this_version": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
    "categories": [],
    "tags": [],
    "group": {
        "id": 3,
        "url": "https://{domain}/services/api/v1.x/groups/3/",
        "name": "My group",
        "country": "NZ"
    },
    "url_html": "https://{domain}/set/2/",
    "metadata": null,
    "publish_to_catalog_services": false,
    "active_publish": null,
    "permissions": "https://{domain}/services/api/v1.x/sets/2/permissions/",
    "settings": {
        "lock_title_to_metadata": false,
        "lock_description_to_metadata": false,
        "lock_tags_to_metadata": false
    },
    "items": [
        "https://{domain}/services/api/v1.x/layers/2/",
        "https://{domain}/services/api/v1.x/layers/1/"
    ],
    "version": {
        "id": 2,
        "url": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
        "created_at": "2020-05-19T04:25:07.390291Z"
    }
}
PUT/sets/{id}/versions/{version}/Edit set version

Edits this set version. If the version isn’t a draft, a 405 response is returned. Accepts same fields as GET above, but ignores the version object.

Response 200

Body

{
    "id": 2,
    "title": "a collection with updated data",
    "url": "https://{domain}/services/api/v1.x/sets/2/",
    "type": "set",
    "created_at": "2020-05-19T04:25:07.220568Z",
    "thumbnail_url": "",
    "description": "My favourite layers",
    "description_html": "<p>My favourite layers</p>",
    "latest_version": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
    "published_version": null,
    "this_version": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
    "categories": [],
    "tags": [],
    "group": {
        "id": 3,
        "url": "https://{domain}/services/api/v1.x/groups/3/",
        "name": "My group",
        "country": "NZ"
    },
    "url_html": "https://{domain}/set/2/",
    "metadata": null,
    "publish_to_catalog_services": false,
    "active_publish": null,
    "permissions": "https://{domain}/services/api/v1.x/sets/2/permissions/",
    "settings": {
        "lock_title_to_metadata": false,
        "lock_description_to_metadata": false,
        "lock_tags_to_metadata": false
    },
    "items": [
        "https://{domain}/services/api/v1.x/layers/2/",
        "https://{domain}/services/api/v1.x/layers/1/"
    ],
    "version": {
        "id": 2,
        "url": "https://{domain}/services/api/v1.x/sets/2/versions/2/",
        "created_at": "2020-05-19T04:25:07.390291Z"
    }
}

Response 405

Body

{"not-draft": "This version isn't a draft, so you can't edit it"}
DELETE/sets/{id}/versions/{version}/Delete a set version

Deletes this draft version (revert to published). Returns 204 with no body.

Response 204

Response 405

{"not-draft": "This version isn't a draft, so you can't delete it"}

Publish set version

Section titled “Publish set version”
POST/sets/{id}/versions/{version}/publish/Publish set version

Creates a publish task just for this set version. No POST data. The response is 201 with a publish object (state starts as publishing) and a Location header pointing at it.

PUT/sets/{id}/Update a set

This changes the owner of the set only. Send user or group (one is required); any other field is ignored. To change a set’s title, description, categories, tags or items, edit a draft with Edit set version and publish it. Note that items replaces the existing list.

Request

Headers

Content-Type: application/json

Body

{
    "group": 3
}

Response 200

Headers

Content-Type: application/json

Body

{
    "id": 1,
    "title": "My collection",
    "description": "a collection of layers",
    "description_html": "<p>a collection of layers</p>",
    "categories": [],
    "tags": [],
    "group": {
        "id": 3,
        "url": "https://{domain}/services/api/v1.x/groups/3/",
        "name": "My group",
        "country": "NZ"
    },
    "items": [
        "https://{domain}/services/api/v1.x/layers/2/",
        "https://{domain}/services/api/v1.x/layers/1/"
    ],
    "url": "https://{domain}/services/api/v1.x/sets/1/",
    "url_html": "https://{domain}/set/1-a-collection/",
    "metadata": null,
    "publish_to_catalog_services": true,
    "permissions": "https://{domain}/services/api/v1.x/sets/1/permissions/",
    "created_at": "2012-12-19T23:13:26.324Z"
}
DELETE/sets/{id}/Delete a set

Delete this set (and all its versions).

Response 204