Vector Tiles API

_|

The Vector Tiles API provides access to Magic Lane vector map tiles in Slippy tile format.

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

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

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

The API returns a vector tile in the requested format. Vector tiles use the Mapbox Vector Tile (MVT) specification and contain encoded geographic features that can be rendered by compatible map libraries.

Response Headers

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

Example Requests

Using Authorization header:

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:

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.

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

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

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.