# Vector Tiles API

Last updated:

<!-- -->

October 18, 2026

<!-- -->

\| 3 minutes read

<br />

<br />

[v](/docs/cloud-rest-api/guides/maps-3dscene/CHANGELOG/)

<!-- -->

[1.0.0 Release notes →](/docs/cloud-rest-api/guides/maps-3dscene/CHANGELOG/)

<br />

<br />

The Vector Tiles API provides access to Magic Lane vector map tiles in [Slippy tile format](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames).

:::info Authentication Required All requests to the Vector Tiles API require authentication. Include your API token in the `Authorization` header. :::

***

**Endpoint:** `GET /tiles/{zoom}/{x}/{y}.{format}`

**Base URL:** `https://api.magiclane.net/api/v1`

## Path Parameters[​](#path-parameters "Direct link to Path Parameters")

| Parameter | Type    | Required | Description                                         |
| --------- | ------- | -------- | --------------------------------------------------- |
| `zoom`    | integer | Yes      | Tile zoom level. Higher values provide more detail. |
| `x`       | integer | Yes      | Tile column in Slippy tile format.                  |
| `y`       | integer | Yes      | Tile row in Slippy tile format.                     |
| `format`  | string  | Yes      | Output format. Supported values: `mvt`, `pbf`.      |

## Authentication[​](#authentication "Direct link to Authentication")

The API supports two authentication methods:

| Method          | Parameter       | Location         | Example                              |
| --------------- | --------------- | ---------------- | ------------------------------------ |
| Header          | `Authorization` | Request header   | `-H "Authorization: YOUR_API_TOKEN"` |
| Query Parameter | `authToken`     | URL query string | `?authToken=YOUR_API_TOKEN`          |

## Response[​](#response "Direct link to Response")

The API returns a vector tile in the requested format. Vector tiles use the [Mapbox Vector Tile (MVT) specification](https://github.com/mapbox/vector-tile-spec) and contain encoded geographic features that can be rendered by compatible map libraries.

### Response Headers[​](#response-headers "Direct link to Response Headers")

| Header         | Description                                            |
| -------------- | ------------------------------------------------------ |
| `Content-Type` | `application/vnd.mapbox-vector-tile` for `.mvt` format |

## Example Requests[​](#example-requests "Direct link to Example Requests")

**Using Authorization header:**

```bash
curl -X GET "https://api.magiclane.net/api/v1/tiles/2/2/1.mvt" \
  -H "Authorization: YOUR_API_TOKEN" \
  --output 2_2_1.mvt

```

**Using query parameter:**

```bash
curl -X GET "https://api.magiclane.net/api/v1/tiles/2/2/1.mvt?authToken=YOUR_API_TOKEN" \
  --output 2_2_1.mvt

```

Both examples request a vector tile at zoom level 2, column 2, row 1 in MVT format.

## Live Demo[​](#live-demo "Direct link to Live Demo")

[Vector Tiles Demo](/docs/cloud-rest-api/demos/vector-tiles-map/index.html)

## Understanding Slippy Tile Coordinates[​](#understanding-slippy-tile-coordinates "Direct link to Understanding Slippy Tile Coordinates")

Slippy tiles use a coordinate system where:

* **Zoom level**: Determines the map detail level. At zoom 0, the entire world is a single tile. Each zoom level doubles the number of tiles in each dimension.
* **X coordinate**: The tile column, starting from 0 at the left (west) edge.
* **Y coordinate**: The tile row, starting from 0 at the top (north) edge.

The number of tiles at each zoom level is `2^zoom × 2^zoom`. For example:

* Zoom 0: 1 tile (the entire world)
* Zoom 1: 4 tiles (2×2)
* Zoom 2: 16 tiles (4×4)

## Supported Formats[​](#supported-formats "Direct link to Supported Formats")

| Format             | Extension | Description                                                         |
| ------------------ | --------- | ------------------------------------------------------------------- |
| Mapbox Vector Tile | `.mvt`    | Standard vector tile format, widely supported by mapping libraries. |
| Protocol Buffers   | `.pbf`    | Binary format, equivalent to MVT.                                   |

Both formats contain the same data and can be used interchangeably.

## Error Responses[​](#error-responses "Direct link to Error Responses")

| HTTP Status | Description                                                   |
| ----------- | ------------------------------------------------------------- |
| `400`       | Bad Request - Invalid parameters.                             |
| `403`       | Forbidden - Invalid or missing authentication token.          |
| `404`       | Not Found - The requested tile does not exist.                |
| `503`       | Service Unavailable - The service is temporarily unavailable. |
