Azure Maps Route Service (stable:2025-01-01)

2025/09/22 • 2 updated methods

Route_PostSnapToRoads (updated)
Description :  The Snap to Roads API accepts GPS point data, represented as longitude and latitude coordinates, and generates points that aligns with existing roadways on a map. This process, known as "snapping to roads", produces a series of objects that trace a path closely following the road network. The resulting data includes road names and their respective speed limits, pertinent to the traversed segments. Moreover, the Snap to Roads API offers an interpolation feature, which refines the GPS points to create a smoother route that adheres to the road's geometry. This functionality is especially beneficial for asset tracking and enhancing data visualization in mapping applications. >[!Important] > The GPS points must be within 6 kilometer of each other. For information about routing availability in countries/regions, see [Azure Maps routing coverage](https://learn.microsoft.com/azure/azure-maps/routing-coverage?pivots=latest).
Reference :  Link ¶

⚶ Changes

{
  "#id": "Route_PostSnapToRoads",
  "$parameters": {
    "snapToRoadsRequest": {
      "$properties": [
        {
          "#name": "features",
          "Description": {
            "new": "A set of points to snap to road network. You can have a minimum of 2 points and maximum of 100 points and the two consecutive points must be within 6 kilometer of each other and a total road distance of up to 100 kilometers. Refer to [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946) for details on the GeoJSON format.\n\n`Note`: The API will not return a point object in the response for the GPS point that cannot be snapped to a road network.",
            "old": "A set of points to snap to road network. You can have a minimum of 2 points and maximum of 100 points and the two consecutive points must be within 6 kilometer of each other. Refer to [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946) for details on the GeoJSON format.\n\n`Note`: The API will not return a point object in the response for the GPS point that cannot be snapped to a road network."
          }
        }
      ]
    }
  }
}

⚼ Request

POST:  /route/snapToRoads
{
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
x-ms-client-id:
{
Description: Indicates the account intended for use with the Microsoft Entra ID security model. This unique ID for the Azure Maps account can be obtained from the [Azure Maps management plane Account API](/rest/api/maps-management/accounts). For more information on using Microsoft Entra ID security in Azure Maps, see [Manage authentication in Azure Maps](/azure/azure-maps/how-to-manage-authentication). ,
Required: False ,
}
string ,
Accept-Language:
{
Description: Language in which routing results should be returned. For more information, see [Localization support in Azure Maps](https://learn.microsoft.com/azure/azure-maps/supported-languages#routing-v2-services-preview-supported-languages). ,
Required: False ,
}
string ,
snapToRoadsRequest:
{
Description: Request body of SnapToRoads API in GeoJSON format. ,
Required: True ,
}
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
FeatureCollection: Specifies the `GeoJSON` `FeatureCollection` object type. ,
}
,
Required: True ,
}
enum ,
features:
{
Description: A set of points to snap to road network. You can have a minimum of 2 points and maximum of 100 points and the two consecutive points must be within 6 kilometer of each other and a total road distance of up to 100 kilometers. Refer to [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946) for details on the GeoJSON format. `Note`: The API will not return a point object in the response for the GPS point that cannot be snapped to a road network. ,
Required: True ,
}
[
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
Feature: Specifies the `GeoJSON` Feature object type. ,
}
,
Required: True ,
}
enum ,
geometry:
{
Description: A valid `GeoJSON Point` geometry type. Please refer to [RFC 7946](https://tools.ietf.org/html/rfc7946#section-3.1.2) for details. ,
Required: True ,
}
object ,
properties:
{
Description: The properties object is required in a valid GeoJSON but it can be empty since the metadata is not used for snapping to road. ,
Required: True ,
}
object ,
}
,
]
,
interpolate:
{
Description: Specifies whether to return additional points between the snapped points to complete the full route path that smoothly follows the road geometry. The interpolated points will have `isInterpolate:true` in the response which can be used to identify the snapped points from interpolated points. ,
Required: False ,
}
boolean ,
includeSpeedLimit:
{
Description: Specifies whether to include speed limit information for the snapped points in the response. The unit is in kilometers per hour. ,
Required: False ,
}
boolean ,
travelMode:
{
Description: Specifies the routing profile for snapping the points. If unspecified, the default mode is "driving", which optimizes the snapped points for driving routes. ,
Enum:
{
driving: The points are snapped to the road suitable for cars. ,
truck: The points are snapped to the road suitable for truck. ,
}
,
Required: False ,
}
enum ,
}
,
}

⚐ Response (200)

{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
FeatureCollection: Specifies the `GeoJSON` `FeatureCollection` object type. ,
}
,
Required: False ,
}
enum ,
features:
{
Description: `GeoJSON` feature object that contains Geometry object and additional properties. Refer to [RFC 7946, Section 3.2](https://www.rfc-editor.org/rfc/rfc7946#section-3.2) for details. ,
Required: False ,
}
[
object ,
]
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}
Route_PostSnapToRoadsBatch (updated)
Description :  The Snap To Roads Batch API sends batches of up to **100** queries as a single call to the [Snap To Roads API](/rest/api/maps/route/post-snap-to-roads?view=rest-maps-2025-01-01). This API enables efficient processing of multiple queries in one request, reducing the need for individual calls. ### Submit Synchronous Batch Request The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API. ``` POST https://atlas.microsoft.com/route/snapToRoads:batch?api-version=2025-01-01 ``` ### POST Body for Batch Request To send the _snap to roads_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 1 _snap to roads_ queries: ``` { "batchItems": [ { "optionalId": "bbc9c0f6-ab52-49d8-a788-a658fa654c94", "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "Point", "coordinates": [ -122.336691, 47.59085 ] }, "properties": { } }, { "type": "Feature", "geometry": { "type": "Point", "coordinates": [ -122.336023, 47.601616 ] }, "properties": { } } ], "includeSpeedLimit": true, "travelMode": "driving" } ] } ``` A _snap to roads_ batchItem object can accept any of the supported _snap to roads_ [Request body](/rest/api/maps/route/post-snap-to-roads?view=rest-maps-2025-01-01#request-body) The batch should contain at least **1** query. ### Batch Response Model The batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types: - [`SnapToRoadsResponse`](/rest/api/maps/route/post-snap-to-roads#response) - If the query completed successfully. - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.
Reference :  Link ¶

⚶ Changes

{
  "#id": "Route_PostSnapToRoadsBatch",
  "Description": {
    "new": "The Snap To Roads Batch API sends batches of up to **100** queries as a single call to the [Snap To Roads API](/rest/api/maps/route/post-snap-to-roads?view=rest-maps-2025-01-01). This API enables efficient processing of multiple queries in one request, reducing the need for individual calls. \n\n### Submit Synchronous Batch Request\nThe Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API.\n```\nPOST https://atlas.microsoft.com/route/snapToRoads:batch?api-version=2025-01-01\n```\n### POST Body for Batch Request\nTo send the _snap to roads_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 1 _snap to roads_ queries:\n\n\n```\n{\n  \"batchItems\": [\n    {\n      \"optionalId\": \"bbc9c0f6-ab52-49d8-a788-a658fa654c94\",\n      \"type\": \"FeatureCollection\",\n      \"features\": [\n        {\n          \"type\": \"Feature\",\n          \"geometry\": {\n            \"type\": \"Point\",\n            \"coordinates\": [\n              -122.336691,\n              47.59085\n            ]\n          },\n          \"properties\": {\n          }\n        },\n        {\n          \"type\": \"Feature\",\n          \"geometry\": {\n            \"type\": \"Point\",\n            \"coordinates\": [\n              -122.336023,\n              47.601616\n            ]\n          },\n          \"properties\": {\n          }\n        }\n      ],\n      \"includeSpeedLimit\": true,\n      \"travelMode\": \"driving\"\n    }\n  ]\n}\n```\n\nA _snap to roads_ batchItem object can accept any of the supported _snap to roads_ [Request body](/rest/api/maps/route/post-snap-to-roads?view=rest-maps-2025-01-01#request-body) \n\n\nThe batch should contain at least **1** query.\n\n\n### Batch Response Model\nThe batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types:\n\n  - [`SnapToRoadsResponse`](/rest/api/maps/route/post-snap-to-roads#response) - If the query completed successfully.\n\n  - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.\n\n\n",
    "old": "The Snap To Roads Batch API sends batches of up to **100** queries as a single call to the [Snap To Roads API](/rest/api/maps/route/post-snap-to-roads?view=rest-maps-2025-01-01). This API enables efficient processing of multiple queries in one request, reducing the need for individual calls. \n\n### Submit Synchronous Batch Request\nThe Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API.\n```\nPOST https://atlas.microsoft.com/route/snapToRoads:batch?api-version=2025-01-01\n```\n### POST Body for Batch Request\nTo send the _snap to roads_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 2 _snap to roads_ queries:\n\n\n```\n{\n  \"batchItems\": [\n    {\n      \"optionalId\": \"bbc9c0f6-ab52-49d8-a788-a658fa654c94\",\n      \"type\": \"FeatureCollection\",\n      \"features\": [\n        {\n          \"type\": \"Feature\",\n          \"geometry\": {\n            \"type\": \"Point\",\n            \"coordinates\": [\n              -122.336691,\n              47.59085\n            ]\n          },\n          \"properties\": {\n          }\n        }\n      ],\n      \"includeSpeedLimit\": true,\n      \"travelMode\": \"driving\"\n    },\n    {\n      \"optionalId\": \"300af787-589b-4088-accd-56828542e293\",\n      \"type\": \"FeatureCollection\",\n      \"features\": [\n        {\n          \"type\": \"Feature\",\n          \"geometry\": {\n            \"type\": \"Point\",\n            \"coordinates\": [\n              -122.336023,\n              47.601616\n            ]\n          },\n          \"properties\": {\n          }\n        }\n      ],\n      \"includeSpeedLimit\": true,\n      \"travelMode\": \"driving\"\n    }\n  ]\n}\n```\n\nA _snap to roads_ batchItem object can accept any of the supported _snap to roads_ [Request body](/rest/api/maps/route/post-snap-to-roads?view=rest-maps-2025-01-01#request-body) \n\n\nThe batch should contain at least **1** query.\n\n\n### Batch Response Model\nThe batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types:\n\n  - [`SnapToRoadsResponse`](/rest/api/maps/route/post-snap-to-roads#response) - If the query completed successfully.\n\n  - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.\n\n\n"
  }
}

⚼ Request

POST:  /route/snapToRoads:batch
{
x-ms-client-id:
{
Description: Indicates the account intended for use with the Microsoft Entra ID security model. This unique ID for the Azure Maps account can be obtained from the [Azure Maps management plane Account API](/rest/api/maps-management/accounts). For more information on using Microsoft Entra ID security in Azure Maps, see [Manage authentication in Azure Maps](/azure/azure-maps/how-to-manage-authentication). ,
Required: False ,
}
string ,
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
Accept-Language:
{
Description: Language in which routing results should be returned. For more information, see [Localization support in Azure Maps](https://learn.microsoft.com/azure/azure-maps/supported-languages#routing-v2-services-preview-supported-languages). ,
Required: False ,
}
string ,
snapToRoadsBatchRequest:
{
Description: The list of Snap To Roads queries/requests to process. The list can contain a max of 100 queries for sync version and must contain at least 1 query. ,
Required: True ,
}
{
batchItems:
{
Description: The list of queries to process. ,
Required: False ,
}
[
object ,
]
,
}
,
}

⚐ Response (200)

{
summary:
{
Description: Summary for the batch request ,
Required: False ,
}
{
successfulRequests:
{
Description: Number of successful requests in the batch ,
Format: int32 ,
Required: False ,
}
integer ,
totalRequests:
{
Description: Total number of requests in the batch ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
batchItems:
{
Description: Array containing the batch results. ,
Required: False ,
}
[
object ,
]
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}