Vector Tiles API

Stable — This API is stable. Breaking changes will be communicated with a deprecation period.

The Vector Tiles API serves map tiles from PMTiles archives. Tiles are edge-cached globally for optimal performance.

Base URL

https://api.geog.dev/v1/tiles/basemap

basemap is an OSM-compatible basemap and is currently the only tileset available.

Authentication

Vector tile requests require a Bearer token with tiles:read scope:

curl -H "Authorization: Bearer your-api-token" \
  "https://api.geog.dev/v1/tiles/basemap/12/986/1473.mvt" \
  --output tile.mvt

Endpoints

1. Get Vector Tile

Retrieve a vector tile at specific coordinates.

GET/v1/tiles/{tileset}/{z}/{x}/{y}.{ext}

Parameters

Parameter	Type	Required	Description
`tileset`	string	Yes	Tileset identifier (e.g., `basemap`)
`z`	integer	Yes	Zoom level
`x`	integer	Yes	Tile column
`y`	integer	Yes	Tile row
`ext`	string	Yes	Format: `mvt` or `pbf`

Headers

Header	Value	Description
`Authorization`	`Bearer {token}`	API authentication
`Accept-Encoding`	`gzip, deflate`	Compression support

Example Request

curl -H "Authorization: Bearer your-api-token" \
  "https://api.geog.dev/v1/tiles/basemap/14/3947/5895.mvt" \
  --output tile.mvt

Response

Content-Type: application/x-protobuf
Cache-Control: max-age=86400 (configurable)
Body: Binary Mapbox Vector Tile data

Status Codes

Status	Description
200	Tile data returned
204	Tile exists but is empty
400	Invalid tile extension or parameters
401	Unauthorized (invalid token)
404	Tile not found or outside zoom range

2. Tileset Metadata

Get TileJSON metadata for the tileset including bounds, zoom range, and tile URL template.

GET/v1/tiles/{tileset}/metadata

Example Request

curl -H "Authorization: Bearer your-api-token" \
  "https://api.geog.dev/v1/tiles/basemap/metadata"

Response

Returns a TileJSON specification object with tileset information (bounds, min/max zoom, attribution, tile URL template, etc.). Response is cached for 1 hour.

Tile Coordinate System

Uses standard Web Mercator (EPSG:3857) tile coordinates:

Z: Zoom level
X: Tile column (0 to 2^z - 1)
Y: Tile row (0 to 2^z - 1)

Rate Limiting

Free tier organizations are limited to 2,000 tile requests per day. Limits reset at 00:00 UTC.

Paid plans have no rate limits.

Rate limit headers are included on free tier responses:

X-RateLimit-Tiles-Limit: 2000
X-RateLimit-Tiles-Remaining: 1999
X-RateLimit-Tiles-Reset: 2025-01-02T00:00:00.000Z