You are viewing documentation for an older version of the Mapbox API. Check out v4 for the latest.


The {mapid} parameter of requests should contain the API ID of the map you want to display. Each map id contains your account and the id of your map.


Request a 256x256 image tile or UTFGrid for a given {mapid}. The {z}, {x}, and {y} parameters must be integer coordinates describing the tile position according to the XYZ tiling scheme. The tile {format} defaults to png but can be used to adjust the image quality, format, and scale factor.

Image quality & retina

The {format} of any image request can be replaced by any of the following extensions to adjust image quality for different bandwidth requirements. Mapbox reencodes the output image based on the requested format.

For maps that support retina autoscaling, indicated by "autoscale": true in a map's TileJSON, you can prefix any image quality type with @2x to request a high DPI version.

@2x.png2x scale (retina)
png3232 color indexed PNG
png6464 color indexed PNG
png128128 color indexed PNG
png256256 color indexed PNG
jpg7070% quality JPG
jpg8080% quality JPG
jpg9090% quality JPG

HTML embeds{mapid}.html{mapid}/{options}.html

Request embeddable HTML suitable for fullscreen map displays or for inserting into blog posts and articles as <iframe> content. The {options} parameter is a comma-separated list of options that can be included in the request to adjust the configuration of controls and map behaviors in the embed.

zoomwheelEnable zooming using the mouse wheel.
zoompanEnable zoom & pan controls.
geocoderEnable geocoder control.
shareEnable share control.
legendEnable legend control (now automatically included).
tooltipsEnable interactive tooltips (now automatically included).
attributionEnable attribution control (now automatically included).
bwdetectDynamic image format adjustment for low bandwidth users.

Our iframe embeds support hash locations. For instance, the map at

Will acquire the zoom level and centerpoint that you've set in the map editor. You can change this dynamically by specifying zoom level, latitude, and longitude in the URL

This example will center the map at zoom level 12, 38 degrees latitude, and -77 degrees longitude.

GeoJSON & KML{mapid}/markers.geojson{mapid}/markers.kml

Request point, polygon, or line features for a given {mapid}. When using GeoJSON the response contains a FeatureCollection with features that conform to the simplestyle-spec for styling GeoJSON data. An optional KML endpoint is also available.


Request TileJSON metadata for a given {mapid}. Include the ?secure querystring in the request to have resources in the TileJSON reference HTTPS endpoints. The TileJSON response always includes the following keys and additional custom metadata may be included for uploaded maps.

tilejsonThe TileJSON spec version implemented.
schemeTiling scheme used by the map tiles.
tilesTemplated URLs to map tiles.
minzoomMin zoom level supported.
maxzoomMax zoom level supported.
centerInitial map center to use when initializing the viewport.
boundsBounds of the map extent.
webpageURL of sharable webpage for the map.
idOptional. Mapbox map ID.
nameOptional. Name of the map.
descriptionOptional. Description of the map.
gridsOptional. Templated URLs to UTFGrids.
dataOptional. Templated URLs to feature geojson.
attributionOptional. Attribution text.
legendOptional. Legend text.
autoscaleOptional. True for maps that support the @2x HiDPI suffix.
downloadOptional. URL to download MBTiles uploads.
filesizeOptional. Original filesize of MBTiles uploads.

Lists{account}/maps.json{account}/tilesets.json deprecated

Request an array of public map TileJSON objects for a given account. The maps.json endpoint returns both projects and data, while tilesets.json contains only data uploads for a given account. The {account} parameter of requests should be a valid Mapbox account id.