Legacy Maps

warning
Note

The Legacy Map API is a legacy product. It is no longer in active development. To learn more about Mapbox's newer web services APIs see the Styles API documentation on the endpoint to request embeddable HTML.

Legacy Maps

The Mapbox Legacy Maps API supports the retrieval of tilesets as embeddable HTML slippy maps. You can also use the Legacy Maps API to retrieve a standalone marker.

Retrieve an HTML slippy map

get
/v4/{map_id}/{options}.html{#hash}

Given a valid Mapbox tileset ID, returns HTML for a slippy map that can be used for sharing or embedding.

Required parametersDescription
map_idUnique identifier for the tileset in the format username.id

You can further refine the results from this endpoint with the following optional parameters:

Optional parametersDescription
optionsA comma-separated list of controls and map behaviors to be included in the map:
  • zoomwheel: Enable zooming with the mouse wheel
  • zoompan: Enable zoom and pan controls
  • geocoder: Add a geocoder control to the result slippy map
  • share: Add a share control
hashSpecify a zoom level and location for the map to center on, in the format #zoom/lat/lon. Note: This hash is placed after the access_token in the request.

Example request: Retrieve an HTML slippy map

# Returns a map with zoom and pan controls, a geocoder, and a share control

$ curl "https://api.mapbox.com/v4/mapbox.satellite/zoomwheel,zoompan,geocoder,share.html?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Retrieve an HTML slippy map

Returns HTML for a slippy map that can be used for sharing or embedding.

Retrieve a standalone marker

get
/v4/marker/{name}-{label}+{color}{@2x}.png

Request a single marker image without an accompanying background map.

Required parametersDescription
nameMarker shape and size. Options are pin-s and pin-l.

You can further refine the results from this endpoint with the following optional parameters:

Optional parametersDescription
labelA Maki v0.5.0 icon value. Options are an alphanumeric label a through z, 0 through 99, or a valid Maki icon. If a letter is requested, it will be rendered in uppercase only.
colorA 3- or 6-digit hexadecimal color code. The default color is gray.
@2xInclude to request a high DPI version of the image.

Example request: Retrieve a standalone marker

# Returns a small red marker that contains a car icon, high DPI version

$ curl "https://api.mapbox.com/v4/marker/pin-s-car+f44@2x.png?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Returns a small blue marker labeled A

$ curl "https://api.mapbox.com/v4/marker/pin-s-a+00f.png?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Endpoint support

Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

Response: Retrieve a standalone marker

Returns the requested marker.

Maps API restrictions and limits

  • Use of the Mapbox Legacy Maps API is rate limited based on your user plan. The default is 100,000 requests per minute. If you require a higher rate limit, contact us.
  • Exceeding your user plan's number requests per minute will result in an HTTP 429 Too Many Requests response.
  • For information on rate limit headers, see the Rate limit headers section.