Raster Tiles API | Mappinest Docs

Raster tiles endpoint

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

GET

https://api.mappinest.com/tiles/{datasetId}/{z}/{x}/{y}.{format}?key=YOUR_KEY

Required parameter	Type	Description
`datasetId`	`string`	Unique identifier for the uploaded dataset, typically in the form `username.dataset` unless the dataset 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 raster tiles. Accepted values: `png`, `jpg`, `webp`, or `avif` depending on the dataset and delivery setup.
`key`	`string`	API key passed as the `?key=` query parameter used to authorize the tile request.

Common raster format: PNG.
Additional image extensions such as JPG, WEBP, or AVIF may be available depending on the dataset and delivery setup.
Works well with raster-based clients and GIS tools.

Protected datasets require a Mappinest 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.

Raster Tiles API pricing

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

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

Caching and performance

Raster tile responses are optimized for long-lived caching so repeated image requests stay fast and predictable.

Cache-Control: public, max-age=1209600, immutable keeps raster tiles cacheable for 14 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.