Sign in
Routing

Snap To Road

Nextbillion.ai Snap To Roads API takes a series of locations along a route, and returns the new locations on this route that are snapped to the best-matched roads where the trip took place. You can set various parameters, such as timestamps or radius, to optimize the result.

get/snapToRoads/json

Query parameters

keystring 32 character alphanumeric string required
Example:key=API_KEY

A key is a unique identifier that is required to authenticate a request to the API.

pathstring latitude_1,longitude_1|latitude_2,longitude_2|... required
Example:path=41.38602272,2.17621539|41.38312885,2.17207083|41.38157854,2.17906668|41.38288511,2.18186215

Pipe-separated list of coordinate points along a path which would be snapped to a road.

timestampsstring timestamps_1|timestamps_2|...
Example:timestamps=1656570000|1656570015|1656570030

Pipe-separated UNIX epoch timestamp in seconds for each location. If used, the number of timestamps must be equal to the number of coordinate points in the "path" parameter. The "timestamps" must increase monotonically starting from the first timestamp. This means that each subsequent timestamp should either be more than or equal to the preceding one.

radiusesstring radius_1|radius_2|...
Example:radiuses=14|16|14

Pipe separated radiuses, in meters (m), up to which a coordinate point can be snapped. Please note, if no valid road is available within the specified radius, the API would snap the points to nearest, most viable road. When using this parameter, it is recommended to specify as many radius values as the number of points in "path" parameter. If the same number of "radiuses" are not provided, the API will use the default radius value of 25 meters for all locations.

approaches'unrestricted' | 'curb' approaches_1;approaches_2;...
Example:approaches=unrestricted;;curb;

A semicolon-separated list indicating the side of the road from which to approach the locations on the snapped route. When set to "unrestricted" a route can arrive at the snapped location from either side of the road and when set to "curb" the route will arrive at the snapped location on the driving side of the region. Please note the number of values provided must be equal to the number of coordinate points provided in the "path" parameter. However, you can skip a coordinate and show its position in the list with the ";" separator.

avoid'toll' | 'ferry' | 'highway' | 'none' value_1|value_2|...
Example:avoid=highway|toll

Setting this will ensure the route avoids ferries, tolls, highways or nothing. Multiple values should be separated by a pipe (|). If "none" is provided along with other values, an error is returned as a valid route is not feasible. Please note that when this parameter is not provided in the input, ferries are set to be avoided by default. When this parameter is provided, only the mentioned objects are avoided.

geometry'polyline' | 'polyline6' | 'geojson'
Example:geometry=polyline

Sets the output format of the route geometry in the response. Only the "polyline" or "polyline6" encoded "geometry" of the snapped path is returned in the response depending on the value provided in the input. When "geojson" is selected as the input value, "polyline6" encoded geometry of the snapped path is returned along with a "geojson" object.

mode'car' | 'truck'
Example:mode=car

Set which driving mode the service should use to determine a route. For example, if you use "car", the API will return a route that a car can take. Using "truck" will return a route a truck can use, taking into account appropriate truck routing restrictions.

Note: Only the "car" profile is enabled by default. Please note that customized profiles (including "truck") might not be available for all regions. Please contact your NextBillion.ai account manager, sales representative or reach out at support@nextbillion.ai in case you need additional profiles.

tolerate_outlierboolean

Enable it to ignore locations outside the service boundary. When "true", the service would ignore "path" coordinates points falling outside the accessible area, which otherwise would cause an error when this parameter is "false".

option'flexible'
Example:option=flexible

Include this parameter in the request to return segment-wise speed information of the route returned in the response.

Please note that returning speed information is a function of "road_info" parameter, which is effective only when "option=flexible". However, the resultant route might not contain all the locations provided in "path" input.

road_info'max_speed'
Example:road_info=max_speed

Use this parameter to receive segment-wise maximum speed information of the route in the response. "max_speed" is the only allowed value.

Response

statusstring

A string indicating the state of the response. On normal responses, the value will be Ok. Indicative HTTP error codes are returned for different errors. See the API Errors Codes section below for more information.

msgstring

Displays the error message in case of a failed request or operation. Please note that this parameter is not returned in the response in case of a successful request.

distanceinteger

The total distance of the snapped path in meters.

geometrystring[]

An array of strings containing the encoded geometries of snapped paths in polyline or polyline6 format.

Changes

Changed in 3 of the 15 revisions of this API.3627

  • 7ee76f0ff679129See the full diff
    • ▲

      for the query request parameter approaches, default value was changed from unrestricted to unrestricted

      request-parameter-default-value-changed

    • ▲

      for the query request parameter geometry, default value was changed from polyline to polyline

      request-parameter-default-value-changed

    • ▲

      for the query request parameter mode, default value was changed from car to car

      request-parameter-default-value-changed

    • ▲

      removed the enum value car from the query request parameter mode

      request-parameter-enum-value-removed

    • ▲

      removed the enum value curb from the query request parameter approaches

      request-parameter-enum-value-removed

    • ▲

      removed the enum value flexible from the query request parameter option

      request-parameter-enum-value-removed

    • ▲

      removed the enum value geojson from the query request parameter geometry

      request-parameter-enum-value-removed

    • ▲

      removed the enum value max_speed from the query request parameter road_info

      request-parameter-enum-value-removed

    • ▲

      removed the enum value polyline6 from the query request parameter geometry

      request-parameter-enum-value-removed

    • ▲

      removed the enum value polyline from the query request parameter geometry

      request-parameter-enum-value-removed

    • ▲

      removed the enum value truck from the query request parameter mode

      request-parameter-enum-value-removed

    • ▲

      removed the enum value unrestricted from the query request parameter approaches

      request-parameter-enum-value-removed

    • ○

      added the new enum value car to the query request parameter mode

      request-parameter-enum-value-added

    • ○

      added the new enum value curb to the query request parameter approaches

      request-parameter-enum-value-added

    • ○

      added the new enum value flexible to the query request parameter option

      request-parameter-enum-value-added

    • ○

      added the new enum value geojson to the query request parameter geometry

      request-parameter-enum-value-added

    • ○

      added the new enum value max_speed to the query request parameter road_info

      request-parameter-enum-value-added

    • ○

      added the new enum value polyline to the query request parameter geometry

      request-parameter-enum-value-added

    • ○

      added the new enum value polyline6 to the query request parameter geometry

      request-parameter-enum-value-added

    • ○

      added the new enum value truck to the query request parameter mode

      request-parameter-enum-value-added

    • ○

      added the new enum value unrestricted to the query request parameter approaches

      request-parameter-enum-value-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • a800b73f11c1129See the full diff
    • ▲

      for the query request parameter approaches, default value was changed from unrestricted to unrestricted

      request-parameter-default-value-changed

    • ▲

      for the query request parameter geometry, default value was changed from polyline to polyline

      request-parameter-default-value-changed

    • ▲

      for the query request parameter mode, default value was changed from car to car

      request-parameter-default-value-changed

    • ▲

      removed the enum value car from the query request parameter mode

      request-parameter-enum-value-removed

    • ▲

      removed the enum value curb from the query request parameter approaches

      request-parameter-enum-value-removed

    • ▲

      removed the enum value flexible from the query request parameter option

      request-parameter-enum-value-removed

    • ▲

      removed the enum value geojson from the query request parameter geometry

      request-parameter-enum-value-removed

    • ▲

      removed the enum value max_speed from the query request parameter road_info

      request-parameter-enum-value-removed

    • ▲

      removed the enum value polyline from the query request parameter geometry

      request-parameter-enum-value-removed

    • ▲

      removed the enum value polyline6 from the query request parameter geometry

      request-parameter-enum-value-removed

    • ▲

      removed the enum value truck from the query request parameter mode

      request-parameter-enum-value-removed

    • ▲

      removed the enum value unrestricted from the query request parameter approaches

      request-parameter-enum-value-removed

    • ○

      added the new enum value car to the query request parameter mode

      request-parameter-enum-value-added

    • ○

      added the new enum value curb to the query request parameter approaches

      request-parameter-enum-value-added

    • ○

      added the new enum value flexible to the query request parameter option

      request-parameter-enum-value-added

    • ○

      added the new enum value geojson to the query request parameter geometry

      request-parameter-enum-value-added

    • ○

      added the new enum value max_speed to the query request parameter road_info

      request-parameter-enum-value-added

    • ○

      added the new enum value polyline6 to the query request parameter geometry

      request-parameter-enum-value-added

    • ○

      added the new enum value polyline to the query request parameter geometry

      request-parameter-enum-value-added

    • ○

      added the new enum value truck to the query request parameter mode

      request-parameter-enum-value-added

    • ○

      added the new enum value unrestricted to the query request parameter approaches

      request-parameter-enum-value-added

  • b79d96775b13129See the full diff
    • ▲

      for the query request parameter approaches, default value was changed from unrestricted to unrestricted

      request-parameter-default-value-changed

    • ▲

      for the query request parameter geometry, default value was changed from polyline to polyline

      request-parameter-default-value-changed

    • ▲

      for the query request parameter mode, default value was changed from car to car

      request-parameter-default-value-changed

    • ▲

      removed the enum value car from the query request parameter mode

      request-parameter-enum-value-removed

    • ▲

      removed the enum value curb from the query request parameter approaches

      request-parameter-enum-value-removed

    • ▲

      removed the enum value flexible from the query request parameter option

      request-parameter-enum-value-removed

    • ▲

      removed the enum value geojson from the query request parameter geometry

      request-parameter-enum-value-removed

    • ▲

      removed the enum value max_speed from the query request parameter road_info

      request-parameter-enum-value-removed

    • ▲

      removed the enum value polyline6 from the query request parameter geometry

      request-parameter-enum-value-removed

    • ▲

      removed the enum value polyline from the query request parameter geometry

      request-parameter-enum-value-removed

    • ▲

      removed the enum value truck from the query request parameter mode

      request-parameter-enum-value-removed

    • ▲

      removed the enum value unrestricted from the query request parameter approaches

      request-parameter-enum-value-removed

    • ○

      added the new enum value car to the query request parameter mode

      request-parameter-enum-value-added

    • ○

      added the new enum value curb to the query request parameter approaches

      request-parameter-enum-value-added

    • ○

      added the new enum value flexible to the query request parameter option

      request-parameter-enum-value-added

    • ○

      added the new enum value geojson to the query request parameter geometry

      request-parameter-enum-value-added

    • ○

      added the new enum value max_speed to the query request parameter road_info

      request-parameter-enum-value-added

    • ○

      added the new enum value polyline to the query request parameter geometry

      request-parameter-enum-value-added

    • ○

      added the new enum value polyline6 to the query request parameter geometry

      request-parameter-enum-value-added

    • ○

      added the new enum value truck to the query request parameter mode

      request-parameter-enum-value-added

    • ○

      added the new enum value unrestricted to the query request parameter approaches

      request-parameter-enum-value-added