Cartography API

For creating and publishing cartographic styles for Layers and Sets.

Custom styles

Spatial layers and sets can have custom styles. You can manage a style’s metadata, stylesheets and publishing through the API. The examples use /layers/{id}/styles/; the same endpoints work under /sets/{id}/styles/. To set a style’s stylesheet on a layer, include stylesheets when you create or edit the style: either a string holding the stylesheet (for example, CartoCSS), or an array of {"id": "style.mss", "data": "…"} objects.

A style can have one of a number of statuses:

• NEW - The style has been created but never published.
• GENERATING - The style is being published for the first time.
• GENERATING - ERROR - The style failed to publish the first time.
• ACTIVE - The style is published and active.
• MODIFIED - The style is active, but a pending change is unpublished.
• UPDATING - The style is active, but a change is being published.
• UPDATING - ERROR - A change to the style failed to publish.

Layer style list

GET/layers/{id}/styles/Get layer or set style list

Returns a paginated list of styles for this layer or set (an empty list, [], if it has none).

Response 200

Headers

Content-Type: application/json

Body

[
    {
        "id": 10,
        "name": "Coloured Boundary Points",
        "url": "https://{domain}/services/api/v1.x/layers/123/styles/10/",
        "state": "NEW",
        "description": "A fake style for these fake boundary points.",
        "created_at": "2014-06-27T00:36:52.723Z",
        "published_at": null,
        "is_default": false
    }
]

POST/layers/{id}/styles/Create a new style

name is required.

Request

Body

{
    "name": "Coloured Boundary Points"
}

Response 201

Headers

Location: https://{domain}/services/api/v1.x/layers/123/styles/10/

Body: the new style, as in the style list (not wrapped in an array).

{
    "id": 10,
    "name": "Coloured Boundary Points",
    "url": "https://{domain}/services/api/v1.x/layers/123/styles/10/",
    "state": "NEW",
    "description": "",
    "created_at": "2014-06-27T00:36:52.723Z",
    "published_at": null,
    "is_default": false
}

Style detail

PUT/layers/{id}/styles/{style}/Edit a style

Styles with an existing state of ACTIVE will become MODIFIED on success.

Request

Body

{
    "name": "Coloured Points"
}

Response 200

Headers

Content-Type: application/json

Body

{
    "id": 10,
    "name": "Coloured Points",
    "url": "https://{domain}/services/api/v1.x/layers/123/styles/10/",
    "state": "NEW",
    "description": "A fake style for these fake boundary points.",
    "created_at": "2014-06-27T00:36:52.723Z",
    "published_at": null,
    "is_default": false
}

DELETE/layers/{id}/styles/{style}/Delete a style

Response 204

Style stylesheets

GET/layers/{id}/styles/{style}/draft/Get a style's draft stylesheets

GET/layers/{id}/styles/{style}/published/Get a style's published stylesheets

These return the style’s stylesheets as an array of id and data objects. The published view returns 204 if the style has never been published. If the style has no stylesheets (for example a style on a set), both return 404.

Style publishing

POST/layers/{id}/styles/{style}/publish/Publish a style

This starts tile generation processes; once complete, the designated style becomes available.

Response 202

Headers

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

Body

{
    "id": 10,
    "name": "Coloured Points",
    "url": "https://{domain}/services/api/v1.x/layers/123/styles/10/",
    "state": "GENERATING",
    "description": "A fake style for these fake boundary points.",
    "created_at": "2014-06-27T00:36:52.723Z",
    "published_at": null,
    "is_default": false
}

The state in the response can already be ACTIVE when there is nothing to generate, for example a style on a set.

Response 400

Headers

Content-Type: application/json

Body

{
    "not-publishable": "This style cannot be published at this time."
}