The Surface API is in private beta and is subject to change. Read more about this new API on our blog.

Surface API

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

The API combines a fast 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 Surface API is powered by vector tilesets. You can upload your own data as tilesets in Mapbox Studio or use the Mapbox Terrain tileset.

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 tileset to calculate volume of a quarry

Querying vector data types

The Surface API works with polyline and polygon data stored in vector tilesets.

Polygons

A query point for a polygon feature returns the feature at that location. If there is no polygon in the layer 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

https://api.mapbox.com/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-v2.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-v2.json?layer=contour&fields=ele&encoded_polyline=w_pfFt%60elVq%40BaBhBc%40z%40ElAP~%40Qt%40ObAg

Required and optional parameters

Parameter Description Example Default Required/Optional
mapid Mapbox mapid vector source mapbox.mapbox-terrain-v2 none required
layer A layer within the specified mapid contour none required
fields Attribute(s) for the mapid specified. Comma separated for multiple fields ele,index none at least 1 field required
access_token Valid Mapbox access_token none required
geojson If true, returns data as a GeoJSON point true false optional
points Represents the requested data. longitude, latitude separated by ;. Can be used in place of encoded_polyline -122.7,37.9;-122.4,37.7 none optional
encoded_polyline Represents the requested data. Can be used in place of points. Read more about encoded polyline w_pfFt%60elV none optional
z Zoom level to query 14 Maximum of mapid id optional
interpolate Indicates whether or not query values should be interpolated (using weighted average of the data from the two closest lines). true true optional

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 identical to 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 keep the Surface API fast, we have place limits on the type of requests made.

Parameter Limit Notes
points 300 Any request with over 300 points will return a 400 response code
encoded_polyline 300 Any request with over 300 points after the encoded polyline is converted to points, will return a 400 response code
vector tiles 70 The 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 tilesets in Mapbox Studio. To create a new API,

  • Log in to mapbox.com
  • Open mapbox.com/data
  • 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? Check out 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.