Route - Post Snap To Roads

Applies to: see pricing tiers.

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.

For information about routing availability in countries/regions, see Azure Maps routing coverage.

POST https://atlas.microsoft.com/route/snapToRoads?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

Successfully retrieve snap to roads points with additional parameters in the body

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

{
  "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.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
      }
    }
  ]
}

Definitions

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.

SnapToRoadsFeatureProperties

Snap to Roads properties.

SnapToRoadsRequest

This object is the request body.

SnapToRoadsResponse

This object is returned from a successful call.

SnapToRoadsTravelModeEnum

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