Spatial - Get Buffer

Reference

Service:: Maps

API Version:: 1.0

Applies to: S1 pricing tier.

This API returns a FeatureCollection where each Feature is a buffer around the corresponding indexed Feature of the input. The buffer could be either on the outside or the inside of the provided Feature, depending on the distance provided in the input. There must be either one distance provided per Feature in the FeatureCollection input, or if only one distance is provided, then that distance is applied to every Feature in the collection. The positive (or negative) buffer of a geometry is defined as the Minkowski sum (or difference) of the geometry with a circle of radius equal to the absolute value of the buffer distance. The buffer API always returns a polygonal result. The negative or zero-distance buffer of lines and points is always an empty polygon. The input features are provided by a GeoJSON file which is uploaded via Data Upload API and referenced by a unique udid. The GeoJSON file may contain a collection of Point, MultiPoint, Polygon, MultiPolygon, LineString and MultiLineString. GeometryCollection will be ignored if provided.

To test this API, you can upload the sample data from Post Buffer API examples(Request Body without distances array) via Data Upload API and replace the [udid] from the sample request below with the udid returned by Data Upload API.

GET https://{geography}.atlas.microsoft.com/spatial/buffer/json?api-version=1.0&udid={udid}&distances={distances}

URI Parameters

Name	In	Required	Type	Description
format	path	True	JsonFormat	Desired format of the response. Only `json` format is supported.
geography	path	True	string	This parameter specifies where the Azure Maps Creator resource is located. Valid values are us and eu.
api-version	query	True	string	Version number of Azure Maps API.
distances	query	True	string	The list of distances (one per feature or one for all features), delimited by semicolons. For example, 12.34;-56.78. Positive distance will generate a buffer outside of the feature, whereas negative distance will generate a buffer inside of the feature. If the negative distance larger than the geometry itself, an empty polygon will be returned.
udid	query	True	string	The unique id returned from Data Upload API after uploading a valid GeoJSON FeatureCollection object. Please refer to RFC 7946 for details. All the feature's properties should contain `geometryId`, which is used for identifying the geometry and is case-sensitive.

Request Header

Name	Required	Type	Description
x-ms-client-id		string	Specifies which account is intended for usage in conjunction with the Azure AD security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Azure AD security in Azure Maps see the following articles for guidance.

Responses

Name	Type	Description
200 OK	BufferResult	OK
Other Status Codes	ErrorResponse	An unexpected error occurred.

Security

AADToken

These are the Azure Active Directory OAuth2 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.

Notes

This security definition requires the use of the x-ms-client-id header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the Maps management API.

The Authorization URL is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. * The Azure role-based access control is configured from the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs. * Usage of the Azure Maps Web SDK allows for configuration based setup of an application for multiple use cases.

Currently, Azure Active Directory v1.0 or v2.0 supports Work, School, and Guests but does not support Personal accounts.

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

Scopes

Name	Description
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

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: query

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

GetBuffer

Sample Request

GET https://us.atlas.microsoft.com/spatial/buffer/json?api-version=1.0&udid=[udid]&distances=176.3

Sample Response

Status code:: 200

{
  "summary": {
    "udid": "[udid from request]",
    "information": "1 feature processed in user data"
  },
  "result": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "properties": {
          "geometryId": "ExampleId",
          "bufferDist": 176.3
        },
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -111.92483859605078,
                33.5362475
              ],
              [
                -111.92487510409389,
                33.53587682761772
              ],
              [
                -111.92498322523961,
                33.535520399967204
              ],
              [
                -111.92515880445296,
                33.535191914363196
              ],
              [
                -111.92539509432322,
                33.53490399432323
              ],
              [
                -111.92568301436319,
                33.53466770445297
              ],
              [
                -111.9260114999672,
                33.53449212523963
              ],
              [
                -111.9263679276177,
                33.5343840040939
              ],
              [
                -111.9267386,
                33.534347496050785
              ],
              [
                -111.92710927238228,
                33.5343840040939
              ],
              [
                -111.92746570003278,
                33.53449212523963
              ],
              [
                -111.9277941856368,
                33.53466770445297
              ],
              [
                -111.92808210567676,
                33.53490399432323
              ],
              [
                -111.92831839554702,
                33.535191914363196
              ],
              [
                -111.92849397476037,
                33.535520399967204
              ],
              [
                -111.9286020959061,
                33.53587682761772
              ],
              [
                -111.92863860394921,
                33.5362475
              ],
              [
                -111.9286020959061,
                33.53661817238228
              ],
              [
                -111.92849397476037,
                33.5369746000328
              ],
              [
                -111.92831839554702,
                33.53730308563681
              ],
              [
                -111.92808210567676,
                33.537591005676774
              ],
              [
                -111.9277941856368,
                33.53782729554703
              ],
              [
                -111.92746570003278,
                33.53800287476037
              ],
              [
                -111.92710927238228,
                33.5381109959061
              ],
              [
                -111.9267386,
                33.53814750394922
              ],
              [
                -111.9263679276177,
                33.5381109959061
              ],
              [
                -111.9260114999672,
                33.53800287476037
              ],
              [
                -111.92568301436319,
                33.53782729554703
              ],
              [
                -111.92539509432322,
                33.537591005676774
              ],
              [
                -111.92515880445296,
                33.53730308563681
              ],
              [
                -111.92498322523961,
                33.5369746000328
              ],
              [
                -111.92487510409389,
                33.53661817238228
              ],
              [
                -111.92483859605078,
                33.5362475
              ]
            ]
          ]
        }
      }
    ]
  }
}

Definitions

BufferResult	This object is returned from a successful Spatial Buffer call.
BufferSummary
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
ErrorResponse	Error response
GeoJsonFeature	A valid `GeoJSON Feature` object type. Please refer to RFC 7946 for details.
GeoJsonFeatureCollection	A valid `GeoJSON FeatureCollection` object type. Please refer to RFC 7946 for details.
GeoJsonGeometry	A valid `GeoJSON` geometry object. The type must be one of the seven valid GeoJSON geometry types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and GeometryCollection. Please refer to RFC 7946 for details.
GeoJsonGeometryCollection	A valid `GeoJSON GeometryCollection` object type. Please refer to RFC 7946 for details.
GeoJsonLineString	A valid `GeoJSON LineString` geometry type. Please refer to RFC 7946 for details.
GeoJsonMultiLineString	A valid `GeoJSON MultiLineString` geometry type. Please refer to RFC 7946 for details.
GeoJsonMultiPoint	A valid `GeoJSON MultiPoint` geometry type. Please refer to RFC 7946 for details.
GeoJsonMultiPolygon	A valid `GeoJSON MultiPolygon` object type. Please refer to RFC 7946 for details.
GeoJsonPoint	A valid `GeoJSON Point` geometry type. Please refer to RFC 7946 for details.
GeoJsonPolygon	A valid `GeoJSON Polygon` geometry type. Please refer to RFC 7946 for details.
JsonFormat	Desired format of the response. Only `json` format is supported.

BufferResult

This object is returned from a successful Spatial Buffer call.

Name	Type	Description
result	GeoJsonFeatureCollection	The FeatureCollection of buffers for the input.
summary	BufferSummary

BufferSummary

Name	Type	Description
information	string	The information about what happened during the call.
udid	string	The udid for the user data if one exists

ErrorAdditionalInfo

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

ErrorDetail

The error detail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	ErrorDetail[]	The error details.
message	string	The error message.
target	string	The error target.

ErrorResponse

Error response

Name	Type	Description
error	ErrorDetail	The error object.

GeoJsonFeature

A valid GeoJSON Feature object type. Please refer to RFC 7946 for details.

Name	Type	Description
featureType	string	The type of the feature. The value depends on the data model the current feature is part of. Some data models may have an empty value.
geometry	GeoJsonGeometry: GeoJsonGeometryCollection GeoJsonLineString GeoJsonMultiLineString GeoJsonMultiPoint GeoJsonMultiPolygon GeoJsonPoint GeoJsonPolygon	A valid `GeoJSON` geometry object. The type must be one of the seven valid GeoJSON geometry types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and GeometryCollection. Please refer to RFC 7946 for details.
id	string	Identifier for the feature.
type	string: Feature	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonFeatureCollection

A valid GeoJSON FeatureCollection object type. Please refer to RFC 7946 for details.

Name	Type	Description
features	GeoJsonFeature[]	Contains a list of valid `GeoJSON Feature` objects.
type	string: FeatureCollection	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonGeometry

A valid GeoJSON geometry object. The type must be one of the seven valid GeoJSON geometry types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and GeometryCollection. Please refer to RFC 7946 for details.

Name	Type	Description
type	GeoJsonObjectType	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonGeometryCollection

A valid GeoJSON GeometryCollection object type. Please refer to RFC 7946 for details.

Name	Type	Description
geometries	GeoJsonGeometry[]: GeoJsonGeometryCollection[] GeoJsonLineString[] GeoJsonMultiLineString[] GeoJsonMultiPoint[] GeoJsonMultiPolygon[] GeoJsonPoint[] GeoJsonPolygon[]	Contains a list of valid `GeoJSON` geometry objects. Note that coordinates in GeoJSON are in x, y order (longitude, latitude).
type	string: GeometryCollection	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonLineString

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

Name	Type	Description
coordinates	array[]	Coordinates for the `GeoJson LineString` geometry.
type	string: LineString	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonMultiLineString

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

Name	Type	Description
coordinates	array[]	Coordinates for the `GeoJson MultiLineString` geometry.
type	string: MultiLineString	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonMultiPoint

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

Name	Type	Description
coordinates	array[]	Coordinates for the `GeoJson MultiPoint` geometry.
type	string: MultiPoint	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonMultiPolygon

A valid GeoJSON MultiPolygon object type. Please refer to RFC 7946 for details.

Name	Type	Description
coordinates	array[]	Contains a list of valid `GeoJSON Polygon` objects. Note that coordinates in GeoJSON are in x, y order (longitude, latitude).
type	string: MultiPolygon	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonPoint

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

Name	Type	Description
coordinates	number[]	A `Position` is an array of numbers with two or more elements. The first two elements are longitude and latitude, precisely in that order. Altitude/Elevation is an optional third element. Please refer to RFC 7946 for details.
type	string: Point	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonPolygon

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

Name	Type	Description
coordinates	array[]	Coordinates for the `GeoJson Polygon` geometry type.
type	string: Polygon	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

JsonFormat

Desired format of the response. Only json format is supported.

Name	Type	Description
json	string	The JavaScript Object Notation Data Interchange Format