---
title: "Snap To Road"
method: GET
path: "/snapToRoads/json"
tags: ["Routing"]
---

# Snap To Road

`GET /snapToRoads/json`

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.

## Query parameters

- `key` string, 32 character alphanumeric string, required
- `path` string, latitude_1,longitude_1|latitude_2,longitude_2|..., required
- `timestamps` string, timestamps_1|timestamps_2|...
- `radiuses` string, radius_1|radius_2|...
- `approaches` 'unrestricted' | 'curb', approaches_1;approaches_2;...
- `avoid` 'toll' | 'ferry' | 'highway' | 'none', value_1|value_2|...
- `geometry` 'polyline' | 'polyline6' | 'geojson'
- `mode` 'car' | 'truck'
- `tolerate_outlier` boolean
- `option` 'flexible'
- `road_info` 'max_speed'

## Response `200`

- object — Response Body
  - `status` string — 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](#api-error-codes) section below for more information.
  - `msg` string — 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.
  - `snappedPoints` object[] — An array of objects. Each object provides the details of a path coordinate point snapped to the nearest road.
    - `location` object, required — The latitude and longitude coordinates of the snapped point.
      - `latitude` number, required — Latitude of the snapped point.
      - `longitude` number, required — Longitude of the snapped point.
    - `originalIndex` integer, required — The index of the input path coordinate point to which this snapped point corresponds to.
    - `distance` number, required — The distance of the snapped point from the original input coordinate in meters.
    - `name` string, required — The name of the street or road that the input coordinate snapped to.
    - `bearing` number, required — The bearing, calculated as the angle from true north in clockwise direction, of the route leading to the next snapped point from the current snapped_point, in radians. In case of the last snapped_point of the route, the bearing indicates the direction of the route to the previous snapped_location.
  - `distance` integer — The total distance of the snapped path in meters.
  - `geometry` string[] — An array of strings containing the encoded geometries of snapped paths in polyline or polyline6 format.
  - `geojson` object — A GeoJSON object with details of the snapped path. This object is returned when the geometry field is set to geojson in the input request, otherwise it is not present in the response. The contents of this object follow the [geoJSON standard](https://datatracker.ietf.org/doc/html/rfc7946).
    - `type` string — Type of the GeoJSON object.
    - `geometry` object — An object with details of the geoJSON geometry of the snapped path.
      - `type` string — Type of the geoJSON geometry
      - `coordinates` number[] — An array of coordinates in the [longitude, latitude] format, representing the snapped path geometry.
    - `properties` string — Properties associated with the geoJSON shape of the snapped path.
  - `road_info` object — An object containing the maximum speed information for each road segment present in the route.
    - `max_speed` object[] — An array of objects containing maximum speed, in kilometers per hour, for each segment of the route. Each object represents one road segment.
      - `offset` integer — offset is the index value of the vertex of route geometry, which is the starting point of the segment.
      - `length` integer — length refers to a sequence of 'n' consecutive vertices in the route geometry starting from the offset, forming a continuous section of route where the maximum speed is the same and is indicated in value.
      - `value` number — value denotes the maximum speed of this segment, in kilometers per hour. - A value of "-1" indicates that the speed is unlimited for this road segment. - A value of "0" indicates that there is no information about the maximum speed for this road segment.

---

[API](https://skmtc.net/nextbillion-ai/apis/one-spec-service.md) · [All operations](https://skmtc.net/nextbillion-ai/apis/one-spec-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nextbillion-ai/one-spec-service/versions/b647f1808dda/schema)