Surface API

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 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 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 create your own custom vector tiles in Mapbox Studio Classic or by uploading vector data directly to Mapbox.

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

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.

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/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.