Surface

warning
Note

The Surface API is a legacy product. It is no longer in active development. To learn more about Mapbox's newer web services APIs see the Mapbox API documentation.

The Mapbox Surface API enables flexible querying of data stored in vector tiles on Mapbox, to create results like elevation profiles.

The API combines a closest-point and point-in-polygon search with built-in interpolation. Given a list of locations, we retrieve vector tiles, find the nearest spatial features, extract their data values, and then absolute values and optionally interpolated values in-between, if the interpolate option is specified.

The data that powers the Surface API is stored in Mapbox Vector Tiles, and uploaded to your account. You can query data in our preset data like Mapbox Terrain, or upload vector data directly to Mapbox using Mapbox Studio.

With the Surface API, you can:

  • Load and display an elevation profile for a hike
  • Explore how temperature and altitude are related
  • Use a drone-derived terrain dataset to calculate volume of a quarry

Querying vector data types

The Surface API works with polyline and polygon data stored as Mapbox Vector Tiles.

Polygons

A query point for a polygon feature returns the feature at that location. If no polygon in the layer is at the specified latitude and longitude, the API returns null.

Polylines

Queries for polyline features can either return the closest single feature to the query point, or can interpolate a single value from the two closest lines. If there are no polylines in a queried tile, the API returns null.

Interpolation

By default, if polyline data is queried, the resulting value will be interpolated. weighted average of the data of the two closest lines. With polygon data, no interpolation happens. If you would like interpolation turned off, set interpolate=false in your request.

Format

get
/v4/surface/{mapid}.json?layer={layer}&fields={field}&access_token={access_token}&points={points or encoded_polyline}

Example query with longitude/latitude Points

https://api.mapbox.com/v4/surface/mapbox.mapbox-terrain-v1.json?layer=contour&fields=ele&points=-112.084004,36.05322;-112.083914,36.053573;-112.083965,36.053845

Example query with an encoded polyline

https://api.mapbox.com/v4/surface/mapbox.mapbox-terrain-v1.json?layer=contour&fields=ele&encoded_polyline=w_pfFt%60elVq%40BaBhBc%40z%40ElAP~%40Qt%40ObAg

Required and optional parameters

ParameterDescriptionExampleDefaultRequired/Optional
mapidMapbox mapid vector sourcemapbox.mapbox-terrain-v1nonerequired
layerA layer within the specified mapidcontournonerequired
fieldsAttribute(s) for the mapid specified. Comma separated for multiple fields ele,indexnoneat least one field required
access_tokenValid Mapbox access_tokennonerequired
geojsonIf true, returns data as a GeoJSON pointtruefalseoptional
pointsRepresents the requested data. longitude, latitude separated by ;. Can be used in place of encoded_polyline-122.7,37.9;-122.4,37.7noneoptional
encoded_polylineRepresents the requested data. Can be used in place of points. Read more about encoded polylinew_pfFt%60elVnoneoptional
zZoom level to query14Maximum of mapid idoptional
interpolateIndicates whether or not query values should be interpolated (using weighted average of the data from the two closest lines).truetrueoptional

Response format

The response to a Surface request is a JSON object with the following properties:

  • id: Corresponds to list of location requests.
  • latlng: Contains a lat and lng field.
  • Data fields: The fields will be the same as the requested fields and will contain the values of these fields at the requested locations.

Example Response

Here is the response for the following query:

https://api.mapbox.com/v4/surface/mapbox.mapbox-terrain-v1.json?layer=contour&fields=ele&points=-116.64267,36.23935;-116.64898,36.24107
{
  "results": [
    {
      "id": 0,
      "latlng": {
        "lat": 36.23935,
        "lng": -116.64267
      },
      "ele": 1054.8865029896933
    },
    {
      "id": 1,
      "latlng": {
        "lat": 36.24107,
        "lng": -116.64898
      },
      "ele": 1058.137654290986
    }
  ],
  "attribution": "<a href='https://www.mapbox.com/about/maps/' target='_blank'>&copy; Mapbox</a>"
}

Limits

To optimize the performance of the Surface API, we have placed limits on the type of requests made.

ParameterLimitNotes
points300Any request with over 300 points will return a 400 response code
encoded_polyline300Any request with over 300 points after the encoded polyline is converted to points, will return a 400 response code
vector tiles70The Surface API reads vector tiles directly. Only 70 vector tiles per request can be loaded.

Creating your own Surface API

Any Mapbox map id can be queried. This means you can query your existing maps or upload new sets to Mapbox.com. To create a new API,

  • Log in to mapbox.com
  • Open mapbox.com/studio/tilesets
  • Click Upload Data
  • Select the file to upload. Acceptable file types include:

    • a zipped shapefile
    • .geojson
    • .gpx
    • .kml
    • .mbtiles
  • Grab the mapid, and start querying!

Surface API Playground

Need help creating Surface API requests for a given mapid? Explore the Surface API Playground.

Errors

Surface API requests may fail. For invalid requests, a 400 HTTP status code will be returned.

In some cases, the surface server may be unable to find a route even for a valid request. In that case, a 200 HTTP status code will be returned.

In both cases, the response body will be a JSON object with an error property describing the error.