Map tiles (beta)

Map keys and short-lived tokens for your own apps and pages; tiles are billed per thousand.

map.tiles Beta tile_1k

How to call it

Request schema

Generated from the same validation rules the endpoint runs, so a field cannot be documented without being validated.

POST /v1/map/token

{
    "type": "object",
    "properties": {
        "ttl_seconds": {
            "type": [
                "integer",
                "null"
            ],
            "minimum": 60,
            "maximum": 86400
        }
    },
    "additionalProperties": false
}

Request example

{
    "ttl_seconds": 3600
}

Response

What a successful call returns: the schema of `data` and `meta`, with a description of each field, followed by an example response from a real call.

POST /v1/map/token

Response schema

{
    "description": "A short-lived token for your apps and pages to load map tiles with. The call bills nothing; the tiles are billed per thousand.",
    "data": {
        "type": "object",
        "properties": {
            "token": {
                "type": "string",
                "description": "The token. Send it as `Authorization: Bearer <token>` or give it to the map SDK as its token."
            },
            "expires_at": {
                "type": "string",
                "format": "date-time",
                "description": "When the token stops working (UTC)."
            },
            "base_url": {
                "type": "string",
                "description": "The map service address the token is for."
            },
            "subject": {
                "type": "string",
                "description": "Whom the tiles loaded with the token are counted for: `open:` and your account number."
            }
        },
        "required": [
            "token",
            "expires_at",
            "base_url",
            "subject"
        ]
    },
    "meta": {
        "type": "object",
        "properties": {
            "ttl_seconds": {
                "type": "integer",
                "description": "How long the token is valid, in seconds."
            }
        }
    }
}

Response example

{
    "request_id": "req_01k8zr4n6p8q0s2u4w6y8a0c3e",
    "capability": "map.tiles",
    "billing": {
        "unit": "tile_1k",
        "quantity": 0,
        "counted": true
    },
    "data": {
        "token": "sm1.eyJzdWIiOiJvcGVuOjQyMTciLCJleHAiOjE3OTMxMjQ4MDB9.Q2v8m1Xb3dKp7Rz0Yt5Wn9Lc4Hs6Fg2Ja8Ue1Oi3Pk",
        "expires_at": "2026-10-27T15:00:00Z",
        "base_url": "https://maps.example.com",
        "subject": "open:4217"
    },
    "meta": {
        "ttl_seconds": 3600
    }
}

What it costs

Thousands of map tiles, charged fractionally.

Every billable response carries a billing block with the unit, the quantity and how the quantity was derived.

Errors it can return