Route - Post Snap To Roads Batch

SnapToRoads Batch API

Applies to: see pricing tiers.

The Snap To Roads Batch API sends batches of up to 100 queries as a single call to the Snap To Roads API.

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=2024-07-01-preview

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 2 snap to roads queries:

{
  "batchItems": [
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "coordinates": [
              -122.122353,
              47.672662
            ],
            "type": "Point"
          },
          "properties": {
                         
          }
        },
        {
          "type": "Feature",
          "geometry": {
            "coordinates": [
              -122.132452,
              47.644234
            ],
            "type": "Point"
          },
          "properties": {
                             
          }
        }
      ],
      "interpolate": true,
      "includeSpeedLimit": true,
      "travelMode": "driving"
    },
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "coordinates": [
              -122.33669,
              47.590849
            ],
            "type": "Point"
          },
          "properties": {
            "pointIndex": 0
          }
        },
        {
          "type": "Feature",
          "geometry": {
            "coordinates": [
              122.34509,
              47.610524
            ],
            "type": "Point"
          },
          "properties": {
            "pointIndex": 1
          }
        }
      ],
      "interpolate": false,
      "includeSpeedLimit": false,
      "travelMode": "driving"
    }
  ]
}

A snap to roads batchItem object can accept any of the supported snap to roads 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 - If the query completed successfully.

• Error - If the query failed. The response will contain a code and a message in this case.

POST https://atlas.microsoft.com/route/snapToRoads:batch?api-version=2024-07-01-preview

URI Parameters

Request Header

Media Types: "application/geo+json"

Request Body

Media Types: "application/geo+json"

Responses

Security

AADToken

These are the Microsoft Entra OAuth 2.0 Flows. When paired with Azure role-based access control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.

To implement scenarios, we recommend viewing authentication concepts. In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

subscription-key

This is a shared key that is provisioned when creating an Azure Maps resource through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.

With this key, any application is authorized to access all REST APIs. In other words, these can currently be treated as master keys to the account which they are issued for.

For publicly exposed applications, our recommendation is to use server-to-server access of Azure Maps REST APIs where this key can be securely stored.

Type: apiKey
In: header

SAS Token

This is a shared access signature token is created from the List SAS operation on the Azure Maps resource through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.

With this token, any application is authorized to access with Azure role-based access controls and fine-grain control to the expiration, rate, and region(s) of use for the particular token. In other words, the SAS Token can be used to allow applications to control access in a more secured way than the shared key.

For publicly exposed applications, our recommendation is to configure a specific list of allowed origins on the Map account resource to limit rendering abuse and regularly renew the SAS Token.

Type: apiKey
In: header

Examples

A Snap To Roads Batch request containing 1 query

POST https://atlas.microsoft.com/route/snapToRoads:batch?api-version=2024-07-01-preview

{
  "batchItems": [
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "coordinates": [
              -122.336729,
              47.590868
            ],
            "type": "Point"
          },
          "properties": {}
        },
        {
          "type": "Feature",
          "geometry": {
            "coordinates": [
              -122.336042,
              47.601604
            ],
            "type": "Point"
          },
          "properties": {}
        }
      ],
      "includeSpeedLimit": true,
      "travelMode": "driving"
    },
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "coordinates": [
              -122.133269,
              47.6470965
            ],
            "type": "Point"
          },
          "properties": {}
        },
        {
          "type": "Feature",
          "geometry": {
            "coordinates": [
              -74.00487,
              40.71396
            ],
            "type": "Point"
          },
          "properties": {}
        }
      ],
      "travelMode": "driving"
    }
  ]
}

{
  "summary": {
    "successfulRequests": 1,
    "totalRequests": 2
  },
  "batchItems": [
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "coordinates": [
              -122.336769,
              47.590885
            ],
            "type": "Point"
          },
          "properties": {
            "inputIndex": 0,
            "name": "WA-99 N",
            "speedLimitInKilometersPerHour": 80
          }
        },
        {
          "type": "Feature",
          "geometry": {
            "coordinates": [
              -122.336008,
              47.601609
            ],
            "type": "Point"
          },
          "properties": {
            "inputIndex": 1,
            "name": "WA-99 N",
            "speedLimitInKilometersPerHour": 80
          }
        }
      ]
    },
    {
      "error": {
        "code": "BadRequest",
        "message": "The distance between two consecutive points (-122.133269,47.6470965) (-74.00487,40.71396) must be within 2.5 kilometers of each other."
      }
    }
  ]
}

Definitions

ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

FeaturesItemTypeEnum

Specifies the GeoJSON type. The only supported object type is Feature. For more information, see RFC 7946.

FeatureTypeEnum

Specifies the GeoJSON type. The only supported object type is FeatureCollection. For more information, see RFC 7946.

GeoJsonPoint

A valid GeoJSON Point geometry type. Please refer to RFC 7946 for details.

InputSnapToRoadsFeaturesItem

Specifies the input snap to roads points. GeoJSON feature object and additional properties. Refer to RFC 7946 for details.

MapsErrorDetail

The error detail.

MapsErrorResponse

Common error response for Azure Maps APIs to return error details for failed operations.

MapsInnerError

An object containing more specific information than the current object about the error.

PointGeometry

The origin point passed as a valid GeoJSON Geometry object, from which the range polygon should be calculated. Please refer to RFC 7946 for details.

Note: The API will snap the requested origin point to the nearest road network and will use that for range calculation. It will be returned as a center point in the response.

SnapToRoadFeaturesItem

GeoJSON feature object that contains Geometry object and additional properties of the route.

SnapToRoadsBatchRequestBody

The list of snap to roads queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query.

SnapToRoadsBatchRequestItem

Batch Query object

SnapToRoadsBatchResponse

This object is returned from a successful Snap To Roads Batch service call.

SnapToRoadsBatchResponseItem

Batch response item

SnapToRoadsFeatureProperties

Snap to Roads properties.

SnapToRoadsTravelModeEnum

Specifies the routing profile for snapping the points. If unspecified, the default mode is "driving", which optimizes the snapped points for driving routes.