Tile Rendering
maps.guru serves vector tiles in the Mapbox Vector Tile (MVT) format using PMTiles archives stored on Cloudflare R2.
How Tile Loading Works
When you use a maps.guru style URL, vector tiles are loaded automatically. The style JSON returned by the API contains all the necessary tile, sprite, and glyph URLs — already configured with your API key.
const map = new maplibregl.Map({
container: 'map',
style: 'https://maps.guru/api/v1/styles/standard/light/style.json?key=YOUR_KEY'
});
The tile URL format used internally follows the standard {z}/{x}/{y} pattern:
| Parameter | Description |
|---|---|
source | Tile source name (e.g., planet-vector) |
z | Zoom level (0-15) |
x | Tile column |
y | Tile row |
Available Sources
| Source | Description | Max Zoom |
|---|---|---|
planet-vector | Full planet vector tiles with OpenMapTiles schema | 15 |
Vector Tile Layers
The planet-vector source includes these layers:
| Layer | Description | Min Zoom |
|---|---|---|
water | Oceans, lakes, rivers | 0 |
landcover | Forests, parks, farmland | 0 |
boundary | Country, state, admin boundaries | 0 |
transportation | Roads, railways, paths | 4 |
building | Building footprints | 13 |
place | City, town, village labels | 2 |
poi | Points of interest | 12 |
Caching
Tiles are cached at multiple levels for optimal performance:
| Layer | TTL | Effect |
|---|---|---|
| CDN (Cloudflare) | 1 week | Tiles served from nearest edge |
| PMTiles header | 1 hour | Avoids re-reading tile index |
| In-memory | Per instance | Faster directory lookups |
Typical latency:
- CDN hit: ~70ms
- CDN miss: ~200ms (fetches from R2)
- Cold start: ~300-400ms
Fonts and Sprites
Font glyphs and sprite sheets are static assets served publicly — no API key is required. They are included in the style JSON automatically when you use a style URL.
These assets have a 1-year immutable cache and are not counted toward your usage quota.