Vector Tiles API

The Vector Tiles API provides efficient map tile serving using PMTiles format for web mapping applications. Built on Cloudflare Workers for global edge distribution and optimal performance.

Base URL

https://tiles.geog.dev/tiles

Authentication

Vector tile requests require authentication via API key:

curl -H "Authorization: Bearer your-api-key" \
  "https://tiles.geog.dev/tiles/10/163/395.mvt" \
  --output tile.mvt

Tile Format

PMTiles Integration

The API serves vector tiles from PMTiles archives stored in Cloudflare R2, providing:

Efficient storage: Single-file tile archives
Fast access: Direct range requests without extraction
Global CDN: Edge-cached delivery worldwide
Cost-effective: Optimized for serverless architectures

Tile Coordinate System

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

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

Endpoints

1. Get Vector Tile

Retrieve a vector tile at specific coordinates.

GET/tiles/{z}/{x}/{y}.mvt

Parameters

Parameter	Type	Required	Description
`z`	integer	Yes	Zoom level (0-14)
`x`	integer	Yes	Tile X coordinate
`y`	integer	Yes	Tile Y coordinate

Headers

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

Example Request

curl -H "Authorization: Bearer your-api-key" \
  "https://tiles.geog.dev/tiles/12/1024/1543.mvt" \
  --output tile.mvt

Response

Content-Type: application/vnd.mapbox-vector-tile
Content-Encoding: gzip (when supported)
Body: Binary Mapbox Vector Tile data

2. Tile Metadata

Get information about available tile layers and zoom levels.

GET/tiles/metadata

Example Request

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

Example Response

{
  "success": true,
  "data": {
    "name": "Geog Base Map",
    "description": "Comprehensive base map with places, roads, and boundaries",
    "version": "1.0.0",
    "format": "pbf",
    "scheme": "xyz",
    "minzoom": 0,
    "maxzoom": 14,
    "bounds": [-180, -85.0511, 180, 85.0511],
    "center": [0, 0, 2],
    "layers": [
      {
        "id": "places",
        "description": "Points of interest and places",
        "minzoom": 8,
        "maxzoom": 14,
        "fields": {
          "name": "string",
          "category": "string",
          "subcategory": "string"
        }
      },
      {
        "id": "roads",
        "description": "Road network and transportation",
        "minzoom": 0,
        "maxzoom": 14,
        "fields": {
          "name": "string",
          "type": "string",
          "class": "string"
        }
      },
      {
        "id": "boundaries",
        "description": "Administrative boundaries",
        "minzoom": 0,
        "maxzoom": 10,
        "fields": {
          "name": "string",
          "admin_level": "number",
          "type": "string"
        }
      }
    ],
    "attribution": "© Geog Platform contributors",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

3. Tile Grid Info

Get tile grid information for a specific zoom level.

GET/tiles/grid/{z}

Parameters

Parameter	Type	Required	Description
`z`	integer	Yes	Zoom level (0-14)

Example Response

{
  "success": true,
  "data": {
    "zoom": 10,
    "tile_count": 1048576,
    "grid_size": {
      "x": 1024,
      "y": 1024
    },
    "tile_size": 512,
    "extent": 4096,
    "bounds": [-180, -85.0511, 180, 85.0511]
  }
}

Vector Tile Layers

Places Layer

Contains points of interest and geographic places.

Geometry Type: Point Zoom Levels: 8-14

Properties:

{
  "name": "Coffee Shop",
  "category": "restaurant",
  "subcategory": "cafe",
  "brand": "Blue Bottle Coffee",
  "status": "active"
}

Roads Layer

Road network and transportation infrastructure.

Geometry Type: LineString Zoom Levels: 0-14

Properties:

{
  "name": "Main Street",
  "type": "primary",
  "class": "highway",
  "oneway": false,
  "surface": "paved"
}

Boundaries Layer

Administrative and political boundaries.

Geometry Type: Polygon/LineString Zoom Levels: 0-10

Properties:

{
  "name": "California",
  "admin_level": 4,
  "type": "state",
  "iso_code": "US-CA"
}

Water Layer

Water bodies and hydrographic features.

Geometry Type: Polygon Zoom Levels: 0-12

Properties:

{
  "name": "Pacific Ocean",
  "type": "ocean",
  "area": 165200000
}

Buildings Layer

Building footprints and structures.

Geometry Type: Polygon Zoom Levels: 12-14

Properties:

{
  "height": 45.5,
  "levels": 12,
  "type": "commercial"
}

Rate Limiting

Vector tile requests are subject to rate limiting:

Default: 10,000 tile requests per hour
Burst: Up to 1,000 requests per minute
Concurrent: Maximum 50 simultaneous connections

Error Handling

HTTP Status Codes

Status	Description
200	Tile successfully served
204	No content (empty tile)
401	Unauthorized (invalid API key)
404	Tile not found (out of bounds)
429	Rate limit exceeded
500	Server error

Error Response Format

{
  "success": false,
  "error": {
    "code": "TILE_NOT_FOUND",
    "message": "Tile at z=15/x=1024/y=2048 does not exist",
    "details": {
      "max_zoom": 14,
      "requested_zoom": 15
    }
  }
}

Data Updates

Update Frequency

Places data: Updated weekly
Road network: Updated monthly
Boundaries: Updated quarterly
Buildings: Updated as available

Version Management

Tiles include version information in metadata:

# Check current tile version
curl -H "Authorization: Bearer your-api-key" \
  "https://tiles.geog.dev/tiles/metadata" | jq '.data.version'