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/v1/tiles/{tilesetId}/{z}/{x}/{y}.{format}?key=YOUR_KEY

Required parameter	Type	Description
`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 raster tiles. Accepted values: `png`, `jpg`, `webp`, or `avif` depending on the tileset 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 tileset and delivery setup.
Works well with raster-based clients and GIS tools.

Protected tilesets 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.

Performance guidance

For uploaded raster tilesets, bandwidth is usually the main cost driver. Mappinest checks new uploads for largest tile size, average tile size, and tile resolution where that information can be detected from the tileset.

Free currently supports raster tilesets with individual tiles up to 850 KB and tile resolution up to 256 px. Flex and Pro support 512 px raster tiles, with largest tile limits of 2 MB and 4 MB under standard ingest rules. See Upload Data for the full table.

Use compressed formats such as jpg, webp, or avif when imagery does not require lossless transparency.
Avoid unnecessary high zoom levels across large coverage areas.
Use 512px tiles only when the client and visual quality requirement justify the larger payloads.