Surface API

The Surface API returns road surface and highway type data for each segment of a route. Use it to know what kind of terrain a route covers — for example, to show a breakdown of asphalt vs. unpaved trail.

Base URL

https://enhance.maptoolkit.net

Authentication

Add your API key as ?api_key=YOUR_API_KEY to every request. See Authentication for details.

Get Surface Data

Endpoint:

GET  https://enhance.maptoolkit.net/route
POST https://enhance.maptoolkit.net/route

Use a POST request when the geometry is large.

Parameters:

Parameter	Type	Required	Description
`surface`	`1`	Yes	Set to `1` to include surface data in the response.
`geometry`	GeoJSON string	Yes (or `gpx`/`kml`)	A GeoJSON `LineString` or `MultiLineString`.
`gpx`	URL	Yes (or `geometry`/`kml`)	URL to a GPX file.
`kml`	URL	Yes (or `geometry`/`gpx`)	URL to a KML file.
`routeType`	string	No	Vehicle type: `car`, `bike`, or `foot`.
`cache`	`0` or `1`	No	Use cached results if available. Default: `1`.
`callback`	string	No	Wrap the response in a JSONP callback.

Example

GET https://enhance.maptoolkit.net/route?kml=https://example.com/route.kml&surface=1&api_key=YOUR_API_KEY

Response:

{
  "geometry": {
    "type": "MultiLineString",
    "coordinates": [[...]]
  },
  "surface": [[
    { "from": 0.053, "to": 0.088, "highway": "road", "surface": "asphalt" },
    { "from": 0.088, "to": 0.106, "highway": "road", "surface": "paved" },
    { "from": 0.106, "to": 0.241, "highway": "path", "surface": "unpaved" }
  ]]
}

The surface array contains one array per segment of the MultiLineString. Each entry covers a portion of the route.

Field	Description
`from`	Start of this segment as a relative position along the route (0 = start, 1 = end).
`to`	End of this segment as a relative position along the route.
`highway`	Road or path type.
`surface`	Surface material.

Highway Types

Value	Description
`motorway`	Motorway or highway.
`primary`	Primary road.
`road`	Secondary or tertiary road.
`street`	Any other street.
`pedestrian`	Pedestrian zone.
`cycleway`	Dedicated cycle path.
`path`	General path.
`hiking`	Hiking trail.
`mountain_hiking`	Mountain hiking path.
`other`	Any other type.

Surface Types

Value	Description
`asphalt`	Asphalt surface.
`paved`	Paved surface (not asphalt).
`unpaved`	Unpaved surface.
`natural`	Natural ground.
`alpine`	Alpine terrain.
`other`	Any other surface.