Mappinest icon|Docs
Loading account...

Vector Tiles API

Reference for the Mappinest vector tiles endpoint. It covers the XYZ URL pattern, PBF responses, error codes, pricing per tile request, and caching.

Vector tile endpoint

The Vector Tiles API serves vector tiles from hosted vector tilesets. This endpoint returns vector tiles using the standard XYZ tile pattern.

GET
https://api.mappinest.com/v1/tiles/{tilesetId}/{z}/{x}/{y}.{format}?key=YOUR_KEY
Required parameterTypeDescription
tilesetId
string
Unique identifier for the uploaded tileset, typically in the form username.tileset unless the tileset is global.
z
integer
Specifies the tile zoom level using the standard XYZ tile scheme.
x / y
integer
Specifies the tile column (x) and row (y) coordinates in the standard XYZ tile scheme.
format
string
Response format for vector tiles. Use pbf by default. mvt is supported as an alias for the same vector tile payload.
key
string
API key passed as the ?key= query parameter used to authorize the tile request.
  • Returns Mapbox Vector Tiles in PBF format.
  • Ideal for MapLibre GL JS, Mapbox GL JS, and other vector-tile-compatible map clients.
  • Pair this with a style or add the source and layers manually in your map client.

Protected tilesets require an API key. Pass the same ?key= query parameter used throughout the docs, and inspect the X-Cache-Status response header when you want to confirm cache hits.

Vector Tiles API errors

Errors return JSON with error.code and error.message.

Error codeHTTP statusDescription
API_KEY_REQUIRED
401
Send the API key through ?key=YOUR_KEY.
API_KEY_FORBIDDEN / ACCESS_FORBIDDEN
403
Check the API key and its permissions.
API_KEY_ORIGIN_FORBIDDEN
403
Check allowed domains and the request Origin.
TILES_READ_SCOPE_REQUIRED
403
Use a key with tiles:read.
TILESET_ACCESS_FORBIDDEN
403
Check ownership and allowed tilesets.
TILESET_SERVING_SUSPENDED
403
Check account storage notices and tileset status.
INVALID_REQUEST / TILESET_ID_REQUIRED
400
Check the tileset ID and request parameters.
RESOURCE_NOT_FOUND
404
Check the tileset ID, coordinates, PBF format, and zoom range against TileJSON.
METHOD_NOT_ALLOWED
405
Use GET, HEAD, or OPTIONS.
RATE_LIMIT_EXCEEDED
429
Reduce concurrency and retry with backoff. Honor Retry-After when provided.
FREE_QUOTA_REACHED
429
Monthly quota exhausted. Enable PAYG or upgrade in Billing.
UNPAID_INVOICE_GRACE_EXPIRED
402
Pay the overdue invoice to resume serving.
AUTH_SERVICE_UNAVAILABLE
503
Authorization is temporarily unavailable. Retry later.

See shared request and serving errors for other codes.

Vector Tiles API pricing

  • Billed by requests.
  • See rates and request tiers on the pricing page.

Usage of the Vector Tiles API is measured in tile requests. Free-tier limits and overage pricing are listed on the pricing page.

Caching and performance

Vector tile responses are served with cache-friendly headers so repeated requests stay fast across browsers and edge caches.

  • Cache-Control: public, max-age=604800, immutable keeps vector tiles cacheable for 7 days.
  • Vary: Origin, Accept-Encoding keeps cross-origin and compressed responses consistent.
  • Access-Control-Expose-Headers: X-Cache-Status makes cache diagnostics visible in browser tools.
  • Use X-Cache-Status to confirm whether a response was a cache HIT, MISS, or revalidated result.
  • Keep tile URLs stable and avoid adding extra query parameters beyond ?key= when you want higher cache reuse.

Performance guidance

For uploaded vector tilesets, Mappinest checks new uploads for largest tile size, average tile size, vector layer count, and field count per layer.

Free currently supports vector tilesets with individual tiles up to 850 KB. Flex raises the largest tile limit to 2 MB, and Pro supports up to 4 MB under standard ingest rules. See Platform Limits for the full table.

  • Keep only fields used for styling, filtering, labels, or popups.
  • Simplify geometry before tiling when high zoom levels create very large tiles.
  • Avoid carrying full source-table attributes in every vector tile when those details can live in a separate API or database.

What to read next

Last updated: October 20, 2026

PreviousTileJSONNextRaster Tiles API