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

Maps

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.

Tiles

http://api.tiles.mapbox.com/v3/{mapid}/{z}/{x}/{y}.{format}
Examples
http://api.tiles.mapbox.com/v3/examples.map-zr0njcqy/0/0/0.png
http://api.tiles.mapbox.com/v3/examples.map-zr0njcqy/0/0/0.jpg
http://api.tiles.mapbox.com/v3/examples.map-zr0njcqy/0/0/0.grid.json

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.

ExtensionDescription
@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

http://api.tiles.mapbox.com/v3/{mapid}.html
http://api.tiles.mapbox.com/v3/{mapid}/{options}.html
Examples
https://api.tiles.mapbox.com/v3/examples.map-zr0njcqy.html
https://api.tiles.mapbox.com/v3/examples.map-zr0njcqy/zoompan.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.

OptionDescription
zoomwheelEnable zooming using the mouse wheel.
zoompanEnable zoom & pan controls.
geocoderEnable geocoder control.
shareEnable share control.
DeprecatedDescription
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

http://api.tiles.mapbox.com/v3/examples.map-zr0njcqy/zoompan.html

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

http://api.tiles.mapbox.com/v3/examples.map-zr0njcqy/zoompan.html#12/38/-77

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

GeoJSON & KML

http://api.tiles.mapbox.com/v3/{mapid}/markers.geojson
http://api.tiles.mapbox.com/v3/{mapid}/markers.kml
Examples
http://api.tiles.mapbox.com/v3/examples.map-zr0njcqy/markers.geojson
http://api.tiles.mapbox.com/v3/examples.map-zr0njcqy/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.

TileJSON

http://api.tiles.mapbox.com/v3/{mapid}.json
https://api.tiles.mapbox.com/v3/{mapid}.json?secure
Examples
http://api.tiles.mapbox.com/v3/examples.map-zr0njcqy.json
https://api.tiles.mapbox.com/v3/examples.map-zr0njcqy.json?secure

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.

KeyDescription
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

http://api.tiles.mapbox.com/v3/{account}/maps.json
http://api.tiles.mapbox.com/v3/{account}/tilesets.json
http://api.tiles.mapbox.com/v3/albums.json deprecated
Examples
http://api.tiles.mapbox.com/v3/mapbox/maps.json
http://api.tiles.mapbox.com/v3/mapbox/tilesets.json

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.