swagger: '2.0'
info:
title: Microsoft Azure Azure Maps Spatial Service
version: '1.0'
description: Azure Maps Spatial REST APIs
host: atlas.microsoft.com
schemes:
- https
consumes: []
produces:
- application/json
- application/xml
securityDefinitions:
AADToken:
type: oauth2
authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
flow: implicit
description: >-
These are the [Microsoft Entra OAuth
2.0](https://docs.microsoft.com/azure/active-directory/develop/v1-overview)
Flows. When paired with [Azure role-based
access](https://docs.microsoft.com/azure/role-based-access-control/overview)
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](https://aka.ms/amauth). 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](https://aka.ms/amauthdetails).
*
The `Authorization URL` is specific to the Azure public cloud instance.
Sovereign clouds have unique Authorization URLs and Microsoft Entra ID
configurations.
*
The Azure role-based access control is configured from the [Azure
management plane](https://aka.ms/amrbac) via Azure portal, PowerShell,
CLI, Azure SDKs, or REST APIs.
*
Usage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for
configuration based setup of an application for multiple use cases.
* For more information on Microsoft identity platform, see [Microsoft
identity platform
overview](https://learn.microsoft.com/entra/identity-platform/v2-overview).
scopes:
https://atlas.microsoft.com/.default: https://atlas.microsoft.com/.default
SharedKey:
type: apiKey
description: >-
This is a shared key that is provisioned when you [Create an Azure Maps
account](https://docs.microsoft.com/azure/azure-maps/quick-demo-map-app#create-an-azure-maps-account)
in the Azure portal or using PowerShell, CLI, Azure SDKs, or REST API.
With this key, any application can access all REST API. In other words, this key can be used as a master key in the account that they are issued in.
For publicly exposed applications, our recommendation is to use the [confidential client applications](https://docs.microsoft.com/azure/azure-maps/authentication-best-practices#confidential-client-applications) approach to access Azure Maps REST APIs so your key can be securely stored.
name: subscription-key
in: query
SasToken:
type: apiKey
description: >-
This is a shared access signature token is created from the List SAS
operation on the [Azure Maps resource](https://aka.ms/amauth) 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](https://aka.ms/amauth) to limit rendering abuse and regularly renew the SAS Token.
name: SAS Token
in: header
security:
- AADToken:
- https://atlas.microsoft.com/.default
- SharedKey: []
- SasToken: []
responses:
'202':
description: >-
Request Accepted: The request has been accepted for processing. Please use
the URL in the Location Header to retry or access the results.
headers:
Location:
type: string
description: New URL to check for the results of the long-running operation.
'400':
description: >-
Bad request: one or more parameters were incorrectly specified or are
mutually exclusive.
schema:
$ref: '#/definitions/ODataErrorResponse'
'401':
description: >-
Access denied due to invalid subscription key or invalid Microsoft Entra
ID bearer token. Make sure to provide a valid key for an active Azure
subscription and Maps resource. Otherwise, verify the
[WWW-Authenticate](https://tools.ietf.org/html/rfc6750#section-3.1) header
for error code and description of the provided Microsoft Entra ID bearer
token.
schema:
$ref: '#/definitions/ODataErrorResponse'
headers:
WWW-Authenticate:
type: string
description: >-
Bearer realm="https://atlas.microsoft.com/", error="invalid_token",
error_description="The access token expired"
'403':
description: Permission, capacity, or authentication issues.
schema:
$ref: '#/definitions/ODataErrorResponse'
'404':
description: >-
Not Found: the requested resource could not be found, but it may be
available again in the future.
schema:
$ref: '#/definitions/ODataErrorResponse'
'500':
description: An error occurred while processing the request. Please try again later.
schema:
$ref: '#/definitions/ODataErrorResponse'
parameters:
ClientId:
name: x-ms-client-id
description: >-
Specifies which account is intended for usage in conjunction with the
Microsoft Entra ID 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 Microsoft Entra ID security in Azure Maps see
the following [articles](https://aka.ms/amauthdetails) for guidance.
type: string
in: header
required: false
x-ms-parameter-location: client
SubscriptionKey:
name: subscription-key
description: >-
One of the Azure Maps keys provided from an Azure Map Account. Please
refer to this
[article](https://docs.microsoft.com/azure/azure-maps/how-to-manage-authentication)
for details on how to manage authentication.
type: string
in: query
required: false
x-ms-parameter-location: client
ApiVersion:
name: api-version
description: Version number of Azure Maps API. Current version is 1.0
type: string
in: query
required: true
default: '1.0'
x-ms-parameter-location: client
JsonFormat:
name: format
description: Desired format of the response. Only `json` format is supported.
type: string
in: path
required: true
enum:
- json
x-ms-enum:
name: JsonFormat
modelAsString: true
values:
- value: json
description: >-
[The JavaScript Object Notation Data Interchange
Format](https://tools.ietf.org/html/rfc8259)
x-ms-parameter-location: method
TextFormat:
name: format
description: Desired format of the response. Value can be either _json_ or _xml_.
type: string
in: path
required: true
enum:
- json
- xml
x-ms-enum:
name: TextFormat
modelAsString: true
values:
- value: json
description: >-
[The JavaScript Object Notation Data Interchange
Format](https://tools.ietf.org/html/rfc8259)
- value: xml
description: '[The Extensible Markup Language](https://www.w3.org/TR/xml/)'
x-ms-parameter-location: method
Mode:
name: mode
in: query
description: Mode of the geofencing async event mechanism.
required: false
type: string
enum:
- All
- EnterAndExit
x-ms-enum:
name: GeofenceMode
modelAsString: true
values:
- value: All
description: >-
Publish all the query results to Azure Maps account event
subscription.
- value: EnterAndExit
description: >-
Only publish result when user location is considered as crossing
geofencing boarder.
x-ms-parameter-location: method
UdidSpatial:
name: udid
in: query
description: >-
The unique id returned from [Data Upload
API](https://docs.microsoft.com/en-us/rest/api/maps/data/uploadPreview)
after uploading a valid GeoJSON FeatureCollection object. Please refer to
[RFC 7946](https://tools.ietf.org/html/rfc7946#section-3.3) for details.
All the feature's properties should contain `geometryId`, which is used
for identifying the geometry and is case-sensitive.
required: true
type: string
x-ms-parameter-location: method
SpatialDataUploadFormat:
name: dataFormat
description: >-
Data format of the content being uploaded. Currently, only `geojson`
format is supported.
type: string
in: query
required: true
enum:
- geojson
x-ms-enum:
name: SpatialDataUploadFormat
modelAsString: true
values:
- value: geojson
description: >-
[GeoJSON](https://tools.ietf.org/html/rfc7946) is a JSON based
geospatial data interchange format.
x-ms-parameter-location: method
paths:
/spatial/geofence/{format}:
get:
x-publish: true
description: "**Search Geofence Get API**
**Applies to:** S1 Pricing tier.
The Geofence Get API allows you to retrieve the proximity of a coordinate to a
geofence that has been uploaded to the Data service. You can use the
[Data Upload API](https://docs.microsoft.com/en-us/rest/api/maps/data/uploadPreview) to upload
a geofence or set of fences. See [Geofencing GeoJSON data](https://docs.microsoft.com/en-us/azure/azure-maps/geofence-geojson)
for more details on the geofence data format. To query the proximity of a coordinate, you supply the location of the object you are tracking as well
as the ID for the fence or set of fences, and the response will contain information about
the distance from the outer edge of the geofence. A negative value signifies that the
coordinate is inside of the fence while a positive value means that it is outside of the
fence.This API can be used for a variety of scenarios that include things like asset
tracking, fleet management, or setting up alerts for moving objects.
The API supports [integration with Event Grid](https://docs.microsoft.com/azure/azure-maps/azure-maps-event-grid-integration). The isAsync parameter is used to enable integration with Event Grid (disabled by default).
To test this API, you can upload the sample data from Post Geofence API examples (Request Body) via Data Upload API and replace the `{udid}` from the sample request below with the udid returned by Data Upload API.
### Geofencing InnerError code
In geofencing response error contract, `innererror` is an object containing service specific information about the error. `code` is a property in `innererror` which can map to a specific geofencing error type. The table belows shows the code mapping between all the known client error type to the corresponding geofencing error `message`.
innererror.code | error.message
---------------------------- | --------------------------------------
NullDeviceId | Device Id should not be null.
NullUdid\t | Udid should not be null.
UdidWrongFormat| Udid should be acquired from user data ingestion API.
InvalidUserTime| Usertime is invalid.
InvalidSearchBuffer| Searchbuffer is invalid.
InvalidSearchRange| The value range of searchbuffer should be from 0 to 500 meters.
InvalidLatLon| Lat and/or lon parameters are invalid.
InvalidIsAsyncValue| The IsAsync parameter is invalid.
InvalidModeValue| The mode parameter invalid.
InvalidJson| Geofencing data is not a valid json file.
NotSupportedGeoJson| Geofencing data can't be read as a Feature or FeatureCollections.
InvalidGeoJson| Geofencing data is invalid.
NoUserDataWithAccountOrSubscription| Can't find user geofencing data with provided account-id and/or subscription-id.
NoUserDataWithUdid|\tCan't find user geofencing data with provided udId."
operationId: microsoftAzureSpatialGetgeofence
x-ms-examples:
Geofence:
$ref: ./examples/GetGeofence.json
parameters:
- $ref: '#/parameters/ClientId'
- $ref: '#/parameters/SubscriptionKey'
- $ref: '#/parameters/ApiVersion'
- $ref: '#/parameters/JsonFormat'
- name: deviceId
in: query
description: ID of the device
required: true
type: string
- name: udId
in: query
description: >-
The unique id returned from [Data Upload
API](https://docs.microsoft.com/en-us/rest/api/maps/data/uploadPreview)
after uploading a valid GeoJSON FeatureCollection object. Please
refer to [RFC 7946](https://tools.ietf.org/html/rfc7946#section-3.3)
for details. All the feature's properties should contain
`geometryId`, which is used for identifying the geometry and is
case-sensitive.
required: true
type: string
- name: lat
in: query
description: 'The latitude of the location being passed. Example: 48.36.'
required: true
type: number
- name: lon
in: query
description: 'The longitude of the location being passed. Example: -124.63.'
required: true
type: number
- name: z
in: query
description: >-
The sea level in meter of the location being passed. If this
parameter is presented, 2D extrusion is used. Example: 200.
required: false
type: number
- name: userTime
in: query
description: >-
The user request time. If not presented in the request, the default
value is DateTime.Now.
required: false
type: string
- name: searchBuffer
in: query
description: >-
The radius of the buffer around the geofence in meters that defines
how far to search inside and outside the border of the fence against
the coordinate that was provided when calculating the result. The
minimum value is 0, and the maximum is 500. The default value is
50.
required: false
type: number
minimum: 0
maximum: 500
default: 50
- name: isAsync
in: query
description: >-
If true, the request will use async event mechanism; if false, the
request will be synchronized and do not trigger any event. The
default value is false.
required: false
type: boolean
default: false
- $ref: '#/parameters/Mode'
produces:
- application/json
responses:
'200':
description: >-
OK The X-Correlation-id header value is present in an async call's
response and the Event Grid event data. It helps correlate the async
call’s response with the corresponding Event Grid event.
headers:
X-Correlation-id:
description: >-
Value present in an async call's response and the Event Grid
event data. It helps correlate the async call’s response with
the corresponding Event Grid event.
type: string
schema:
$ref: '#/definitions/GeofenceResponse'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
summary: Microsoft Azure Get Spatial Geofence Format
tags:
- Spatial
post:
x-publish: true
description: >-
**Search Geofence Post API**
**Applies to:** S1 Pricing tier.
The
Geofence Post API allows you to retrieve the proximity of a coordinate
to a provided geofence or set of fences. With POST call, you do not
have to upload the fence data in advance, instead you supply the
location of the object you are tracking in query parameters as well as
the fence or set of fences data in post request body. See [Geofencing
GeoJSON
data](https://docs.microsoft.com/en-us/azure/azure-maps/geofence-geojson)
for more details on the geofence data format. The response will contain
information about the distance from the outer edge of the geofence. A
negative value signifies that the coordinate is inside of the fence
while a positive value means that it is outside of the fence.This API
can be used for a variety of scenarios that include things like asset tracking, fleet management, or setting up alerts for moving
objects.
The API supports [integration with Event
Grid](https://docs.microsoft.com/azure/azure-maps/azure-maps-event-grid-integration). The isAsync parameter is used to enable integration with Event Grid
(disabled by default).
operationId: microsoftAzureSpatialPostgeofence
x-ms-examples:
Geofence:
$ref: ./examples/PostGeofence.json
parameters:
- $ref: '#/parameters/ClientId'
- $ref: '#/parameters/SubscriptionKey'
- $ref: '#/parameters/ApiVersion'
- $ref: '#/parameters/JsonFormat'
- name: deviceId
in: query
description: ID of the device
required: true
type: string
- name: lat
in: query
description: 'The latitude of the location being passed. Example: 48.36.'
required: true
type: number
- name: lon
in: query
description: 'The longitude of the location being passed. Example: -124.63.'
required: true
type: number
- name: z
in: query
description: >-
The sea level in meter of the location being passed. If this
parameter is presented, 2D extrusion geofencing is applied. Example:
200.
required: false
type: number
- name: userTime
in: query
description: >-
The user request time. If not presented in the request, the default
value is DateTime.UtcNow.
required: false
type: string
- name: searchBuffer
in: query
description: >-
The radius of the buffer around the geofence in meters that defines
how far to search inside and outside the border of the fence against
the coordinate that was provided when calculating the result. The
minimum value is 0, and the maximum is 500. The default value is
50.
required: false
type: number
minimum: 0
maximum: 500
default: 50
- name: isAsync
in: query
description: >-
If true, the request will use async event mechanism; if false, the
request will be synchronized and do not trigger any event. The
default value is false.
required: false
type: boolean
default: false
- $ref: '#/parameters/Mode'
- name: searchGeofenceRequestBody
in: body
description: The geofencing GeoJSON data.
required: true
schema:
$ref: '#/definitions/GeoJSONFeatureCollection'
produces:
- application/json
responses:
'200':
description: >-
OK The X-Correlation-id header value is present in an async call's
response and the Event Grid event data. It helps correlate the async
call’s response with the corresponding Event Grid event.
headers:
X-Correlation-id:
description: >-
Value present in an async call's response and the Event Grid
event data. It helps correlate the async call’s response with
the corresponding Event Grid event.
type: string
schema:
$ref: '#/definitions/GeofenceResponse'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
summary: Microsoft Azure Post Spatial Geofence Format
tags:
- Spatial
/spatial/buffer/{format}:
post:
x-publish: true
description: >-
**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 may contain a collection of Point, MultiPoint, Polygon,
MultiPolygon, LineString and MultiLineString. GeometryCollection will be
ignored if provided.
operationId: microsoftAzureSpatialPostbuffer
x-ms-examples:
PostBuffer:
$ref: ./examples/PostBuffer.json
parameters:
- $ref: '#/parameters/ClientId'
- $ref: '#/parameters/SubscriptionKey'
- $ref: '#/parameters/ApiVersion'
- $ref: '#/parameters/JsonFormat'
- name: bufferRequestBody
in: body
description: >-
The FeatureCollection and the list of distances (one per feature or
one for all features).
required: true
schema:
$ref: '#/definitions/BufferRequestBody'
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/BufferResponse'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
summary: Microsoft Azure Post Spatial Buffer Format
tags:
- Spatial
get:
x-publish: true
description: >-
**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](https://docs.microsoft.com/en-us/rest/api/maps/data/uploadPreview)
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](https://docs.microsoft.com/en-us/rest/api/maps/spatial/postbuffer#examples)
examples (Request Body without distances array) via [Data Upload
API](https://docs.microsoft.com/en-us/rest/api/maps/data/uploadPreview)
and replace the `{udid}` from the [sample request
below](https://docs.microsoft.com/en-us/rest/api/maps/spatial/getbuffer#examples)
with the udid returned by Data Upload API.
operationId: microsoftAzureSpatialGetbuffer
x-ms-examples:
GetBuffer:
$ref: ./examples/GetBuffer.json
parameters:
- $ref: '#/parameters/ClientId'
- $ref: '#/parameters/SubscriptionKey'
- $ref: '#/parameters/ApiVersion'
- $ref: '#/parameters/JsonFormat'
- $ref: '#/parameters/UdidSpatial'
- name: distances
in: query
description: >-
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.
required: true
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/BufferResponse'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
summary: Microsoft Azure Get Spatial Buffer Format
tags:
- Spatial
/spatial/closestPoint/{format}:
post:
x-publish: true
description: >-
**Applies to**: S1 pricing tier.
This API returns the closest
point between a base point and a given set of target points. The set of
target points is provided by user data in post request body. The user
data may only contain a collection of Point geometry. MultiPoint or
other geometries will be ignored if provided. The algorithm does not
take into account routing or traffic. The maximum number of points
accepted is 100,000. Information returned includes closest point
latitude, longitude, and distance in meters from the closest point.
operationId: microsoftAzureSpatialPostclosestpoint
x-ms-examples:
PostClosestPoint:
$ref: ./examples/PostClosestPoint.json
parameters:
- $ref: '#/parameters/ClientId'
- $ref: '#/parameters/SubscriptionKey'
- $ref: '#/parameters/ApiVersion'
- $ref: '#/parameters/JsonFormat'
- name: lat
in: query
description: >-
The base point latitude of the location being passed. Example:
47.622942.
required: true
type: number
- name: lon
in: query
description: >-
The base point longitude of the location being passed. Example:
-122.316456.
required: true
type: number
- name: numberOfClosestPoints
in: query
description: >-
The number of closest points expected from response. Default: 1,
minimum: 1 and maximum: 50
required: false
type: integer
- name: closestPointRequestBody
in: body
description: >-
The FeatureCollection of Point geometries from which closest point
to source point should be determined. All the feature's properties
should contain `geometryId`, which is used for identifying the
geometry and is case-sensitive.
required: true
schema:
$ref: '#/definitions/GeoJSONFeatureCollection'
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/PostClosestPointResponse'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
summary: Microsoft Azure Post Spatial Closestpoint Format
tags:
- Spatial
get:
x-publish: true
description: >-
**Applies to**: S1 pricing tier.
This API returns the closest
point between a base point and a given set of points in the user
uploaded data set identified by udid. The set of target points is
provided by a GeoJSON file which is uploaded via [Data Upload
API](https://docs.microsoft.com/en-us/rest/api/maps/data/uploadPreview)
and referenced by a unique udid. The GeoJSON file may only contain a
collection of Point geometry. MultiPoint or other geometries will be
ignored if provided. The maximum number of points accepted is 100,000.
The algorithm does not take into account routing or traffic. Information
returned includes closest point latitude, longitude, and distance in
meters from the closest point.
To test this API, you can upload
the sample data from [Post Closest Point
API](https://docs.microsoft.com/en-us/rest/api/maps/spatial/postclosestpoint#examples)
examples (Request Body) via [Data Upload
API](https://docs.microsoft.com/en-us/rest/api/maps/data/uploadPreview)
and replace the `{udid}` from the [sample request
below](https://docs.microsoft.com/en-us/rest/api/maps/spatial/getclosestpoint#examples)
with the udid returned by Data Upload API.
operationId: microsoftAzureSpatialGetclosestpoint
x-ms-examples:
GetClosestPoint:
$ref: ./examples/GetClosestPoint.json
parameters:
- $ref: '#/parameters/ClientId'
- $ref: '#/parameters/SubscriptionKey'
- $ref: '#/parameters/ApiVersion'
- $ref: '#/parameters/JsonFormat'
- $ref: '#/parameters/UdidSpatial'
- name: lat
in: query
description: >-
The base point latitude of the location being passed. Example:
47.622942.
required: true
type: number
- name: lon
in: query
description: >-
The base point longitude of the location being passed. Example:
-122.316456.
required: true
type: number
- name: numberOfClosestPoints
in: query
description: >-
The number of closest points expected from response. Default: 1,
minimum: 1 and maximum: 50
required: false
type: integer
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/GetClosestPointResponse'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
summary: Microsoft Azure Get Spatial Closestpoint Format
tags:
- Spatial
/spatial/pointInPolygon/{format}:
post:
x-publish: true
description: >-
**Applies to**: S1 pricing tier.
This API returns a boolean value
indicating whether a point is inside a set of polygons. The user data
may contain Polygon and MultiPolygon geometries, other geometries will
be ignored if provided. If the point is inside or on the boundary of one
of these polygons, the value returned is true. In all other cases, the
value returned is false. When the point is inside multiple polygons, the
result will give intersecting geometries section to show all valid
geometries (referenced by geometryId) in user data. The maximum number
of vertices accepted to form a Polygon is 10,000.
operationId: microsoftAzureSpatialPostpointinpolygon
x-ms-examples:
PostPointInPolygon:
$ref: ./examples/PostPointInPolygon.json
parameters:
- $ref: '#/parameters/ClientId'
- $ref: '#/parameters/SubscriptionKey'
- $ref: '#/parameters/ApiVersion'
- $ref: '#/parameters/JsonFormat'
- name: lat
in: query
description: >-
The base point latitude of the location being passed. Example:
47.622942.
required: true
type: number
- name: lon
in: query
description: >-
The base point longitude of the location being passed. Example:
-122.316456.
required: true
type: number
- name: pointInPolygonRequestBody
in: body
description: >-
A FeatureCollection with a set of Polygon/MultiPolygon geometries.
The maximum number of vertices accepted to form a Polygon is 10,000.
All the feature's properties should contain `geometryId`, which is
used for identifying the geometry and is case-sensitive.
required: true
schema:
$ref: '#/definitions/GeoJSONFeatureCollection'
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/PostPointInPolygonResponse'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
summary: Microsoft Azure Post Spatial Pointinpolygon Format
tags:
- Spatial
get:
x-publish: true
description: >-
**Applies to**: S1 pricing tier.
This API returns a boolean value
indicating whether a point is inside a set of polygons. The set of
polygons is provided by a GeoJSON file which is uploaded via [Data
Upload
API](https://docs.microsoft.com/en-us/rest/api/maps/data/uploadPreview)
and referenced by a unique udid. The GeoJSON file may contain Polygon
and MultiPolygon geometries, other geometries will be ignored if
provided. If the point is inside or on the boundary of one of these
polygons, the value returned is true. In all other cases, the value
returned is false. When the point is inside multiple polygons, the
result will give intersecting geometries section to show all valid
geometries(referenced by geometryId) in user data. The maximum number of
vertices accepted to form a Polygon is 10,000.
To test this
API, you can upload the sample data from [Post Point In Polygon
API](https://docs.microsoft.com/en-us/rest/api/maps/spatial/postpointinpolygon#examples)
examples (Request Body) via [Data Upload
API](https://docs.microsoft.com/en-us/rest/api/maps/data/uploadPreview)
and replace the `{udid}` from the [sample request
below](https://docs.microsoft.com/en-us/rest/api/maps/spatial/getpointinpolygon#examples)
with the udid returned by Data Upload API.
operationId: microsoftAzureSpatialGetpointinpolygon
x-ms-examples:
GetPointInPolygon:
$ref: ./examples/GetPointInPolygon.json
parameters:
- $ref: '#/parameters/ClientId'
- $ref: '#/parameters/SubscriptionKey'
- $ref: '#/parameters/ApiVersion'
- $ref: '#/parameters/JsonFormat'
- $ref: '#/parameters/UdidSpatial'
- name: lat
in: query
description: >-
The base point latitude of the location being passed. Example:
47.622942.
required: true
type: number
- name: lon
in: query
description: >-
The base point longitude of the location being passed. Example:
-122.316456.
required: true
type: number
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/GetPointInPolygonResponse'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
summary: Microsoft Azure Get Spatial Pointinpolygon Format
tags:
- Spatial
/spatial/greatCircleDistance/{format}:
get:
x-publish: true
description: >-
**Applies to**: S1 pricing tier.
This API will return the
great-circle or shortest distance between two points on the surface of a
sphere, measured along the surface of the sphere. This differs from
calculating a straight line through the sphere's interior. This method
is helpful for estimating travel distances for airplanes by calculating
the shortest distance between airports.
operationId: microsoftAzureSpatialGetgreatcircledistance
x-ms-examples:
GetGreatCircleDistance:
$ref: ./examples/GetGreatCircleDistance.json
parameters:
- $ref: '#/parameters/ClientId'
- $ref: '#/parameters/SubscriptionKey'
- $ref: '#/parameters/ApiVersion'
- $ref: '#/parameters/JsonFormat'
- name: query
in: query
description: >-
The Coordinates through which the distance is calculated, delimited
by a colon. Two coordinates are required. The first one is the
source point coordinate and the last is the target point coordinate.
For example, 47.622942,122.316456:57.673988,127.121513
required: true
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/GreatCircleDistanceResponse'
'400':
$ref: '#/responses/400'
'401':
$ref: '#/responses/401'
'403':
$ref: '#/responses/403'
'404':
$ref: '#/responses/404'
'500':
$ref: '#/responses/500'
summary: Microsoft Azure Get Spatial Greatcircledistance Format
tags:
- Spatial
definitions:
ODataErrorResponse:
type: object
description: >-
This response object is returned when an error occurs in the Azure Maps
API.
properties:
error:
$ref: '#/definitions/ODataError'
ODataError:
type: object
description: This object is returned when an error occurs in the Azure Maps API.
properties:
code:
type: string
readOnly: true
description: The ODataError code.
message:
type: string
readOnly: true
description: If available, a human-readable description of the error.
details:
type: array
items:
$ref: '#/definitions/ODataError'
target:
type: string
readOnly: true
description: If available, the target causing the error.
SpatialCoordinate:
description: A location represented as a latitude and longitude
type: object
properties:
lat:
description: Latitude property
type: number
format: double
readOnly: true
lon:
description: Longitude property
type: number
format: double
readOnly: true
GeoJSONFeatureCollection:
description: >-
A valid `GeoJSON FeatureCollection` object type. Please refer to [RFC
7946](https://tools.ietf.org/html/rfc7946#section-3.3) for details.
type: object
properties:
type:
description: >-
Specifies the `type` for the object. Value should always be equal to
"FeatureCollection".
type: string
features:
description: Contains a list of valid `GeoJSON Feature` objects.
type: array
items:
description: >-
A valid `GeoJSON Feature` object type. Please refer to [RFC
7946](https://tools.ietf.org/html/rfc7946#section-3.2) for details.
type: object
properties:
type:
description: >-
Specifies the `type` for the object. Value should always be
equal to "Feature".
type: string
geometry:
$ref: '#/definitions/GeoJSONGeometry'
properties:
x-ms-client-flatten: true
description: >-
Properties can contain any additional metadata about the
`Feature`. Value can be any JSON object or a JSON null value
type: object
required:
- features
- type
GeoJSONGeometry:
description: >-
A valid `GeoJSON` geometry object. Please refer to [RFC
7946](https://tools.ietf.org/html/rfc7946#section-3.1) for details.
type: object
discriminator: type
required:
- type
properties:
type:
description: >-
Specifies the `GeoJSON` geometry type. Must be one of the seven valid
GeoJSON geometry types - Point, MultiPoint, LineString,
MultiLineString, Polygon, MultiPolygon and GeometryCollection.
type: string
enum:
- Point
- MultiPoint
- LineString
- MultiLineString
- Polygon
- MultiPolygon
- GeometryCollection
x-ms-enum:
name: GeoJSONGeometryType
modelAsString: true
values:
- value: Point
description: '`GeoJSON Point` geometry.'
- value: MultiPoint
description: '`GeoJSON MultiPoint` geometry.'
- value: LineString
description: '`GeoJSON LineString` geometry.'
- value: MultiLineString
description: '`GeoJSON MultiLineString` geometry.'
- value: Polygon
description: '`GeoJSON Polygon` geometry.'
- value: MultiPolygon
description: '`GeoJSON MultiPolygon` geometry.'
- value: GeometryCollection
description: '`GeoJSON GeometryCollection` geometry.'
Point:
description: >-
A valid `GeoJSON Point` geometry type. Please refer to [RFC
7946](https://tools.ietf.org/html/rfc7946#section-3.1.2) for details.
type: object
allOf:
- $ref: '#/definitions/GeoJSONGeometry'
- properties:
type:
description: >-
Specifies the `type` for the geometry. Value should always be
equal to "Point".
type: string
coordinates:
$ref: '#/definitions/GeoJSONPosition'
required:
- coordinates
MultiLineString:
description: >-
A valid `GeoJSON MultiLineString` geometry type. Please refer to [RFC
7946](https://tools.ietf.org/html/rfc7946#section-3.1.5) for details.
type: object
allOf:
- $ref: '#/definitions/GeoJSONGeometry'
- properties:
type:
description: >-
Specifies the `type` for the geometry. Value should always be
equal to "MultiLineString".
type: string
coordinates:
description: Coordinates for the `MultiLineString` geometry.
type: array
items:
type: array
items:
$ref: '#/definitions/GeoJSONPosition'
required:
- coordinates
Polygon:
description: >-
A valid `GeoJSON Polygon` geometry type. Please refer to [RFC
7946](https://tools.ietf.org/html/rfc7946#section-3.1.6) for details.
type: object
allOf:
- $ref: '#/definitions/GeoJSONGeometry'
- properties:
type:
description: >-
Specifies the `type` for the object. Value should always be equal
to "Polygon".
type: string
coordinates:
description: Coordinates for the `Polygon` geometry type.
type: array
items:
$ref: '#/definitions/GeoJSONLinearRing'
required:
- coordinates
MultiPolygon:
description: >-
A valid `GeoJSON MultiPolygon` object type. Please refer to [RFC
7946](https://tools.ietf.org/html/rfc7946#section-3.1.7) for details.
type: object
allOf:
- $ref: '#/definitions/GeoJSONGeometry'
- properties:
type:
description: >-
Specifies the `type` for the object. Value should always be equal
to "MultiPolygon".
type: string
coordinates:
description: >-
Contains a list of valid `GeoJSON` Polygon objects. **Note** that
coordinates in GeoJSON are in x, y order (longitude, latitude).
type: array
items:
type: array
items:
$ref: '#/definitions/GeoJSONLinearRing'
required:
- coordinates
GeoJSONLinearRing:
description: >-
Though a linear ring is not explicitly represented as a GeoJSON geometry
type, it helps in defining the polygon as an array of linear rings. Please
refer to [RFC 7946](https://tools.ietf.org/html/rfc7946#section-3.1.6) for
details.
type: array
items:
$ref: '#/definitions/GeoJSONPosition'
GeoJSONPosition:
description: >-
A valid `GeoJSON Position` geometry type. 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](https://tools.ietf.org/html/rfc7946#section-3.1.1) for details.
type: array
items:
type: number
format: double
GeofenceGeometry:
description: The geofencing geometry.
type: object
readOnly: true
properties:
deviceId:
description: ID of the device.
type: string
readOnly: true
udId:
description: >-
The unique id returned from [Data Upload
API](https://docs.microsoft.com/en-us/rest/api/maps/data/uploadPreview)
after uploading a valid GeoJSON FeatureCollection object. Please refer
to [RFC 7946](https://tools.ietf.org/html/rfc7946#section-3.3) for
details. All the feature's properties should contain `geometryId`,
which is used for identifying the geometry and is case-sensitive.
type: string
readOnly: true
geometryId:
description: The unique id identifies a geometry.
type: string
readOnly: true
distance:
description: >-
Distance from the coordinate to the closest border of the geofence.
Positive means the coordinate is outside of the geofence. If the
coordinate is outside of the geofence, but more than the value of
searchBuffer away from the closest geofence border, then the value is
999. Negative means the coordinate is inside of the geofence. If the
coordinate is inside the polygon, but more than the value of
searchBuffer away from the closest geofencing border, then the value
is -999. A value of 999 means that there is great confidence the
coordinate is well outside the geofence. A value of -999 means that
there is great confidence the coordinate is well within the geofence.
type: number
readOnly: true
nearestLat:
description: Latitude of the nearest point of the geometry.
type: number
readOnly: true
nearestLon:
description: Longitude of the nearest point of the geometry.
type: number
readOnly: true
nearestZ:
description: >-
Sea level in meter of the nearest point on the 2D extrusion geometry.
This will only be presented in response when value is provided for
'zInMeter' in the request.
type: number
readOnly: true
GeofenceResponse:
description: This object is returned from a geofence proximity call.
type: object
properties:
geometries:
description: >-
Lists the fence geometries that contain the coordinate position or
overlap the searchBuffer around the position.
type: array
readOnly: true
items:
$ref: '#/definitions/GeofenceGeometry'
expiredGeofenceGeometryId:
description: >-
Lists of the geometry ID of the geofence which is expired relative to
the user time in the request.
type: array
readOnly: true
items:
type: string
invalidPeriodGeofenceGeometryId:
description: >-
Lists of the geometry ID of the geofence which is in invalid period
relative to the user time in the request.
type: array
readOnly: true
items:
type: string
isEventPublished:
description: >-
True if at least one event is published to the Azure Maps event
subscriber, false if no event is published to the Azure Maps event
subscriber. This will only be presented in response when 'isAsync'
query parameter is set to true.
type: boolean
readOnly: true
BufferRequestBody:
description: >-
An object with a FeatureCollection and a list of distances. All the
feature's properties should contain `geometryId`, which is used for
identifying the geometry and is case-sensitive.
type: object
properties:
geometries:
$ref: '#/definitions/GeoJSONFeatureCollection'
distances:
description: >-
List of the distances to compute the buffer for, one-to-one per
Feature in the collection, or one for all Features in the collection.
type: array
items:
type: number
BufferResponse:
description: This object is returned from a successful Spatial Buffer call.
type: object
properties:
summary:
description: Summary of the call.
type: object
readOnly: true
properties:
udid:
description: The udid for the user data if one exists
type: string
readOnly: true
information:
description: The information about what happened during the call.
type: string
readOnly: true
result:
description: The FeatureCollection of buffers for the input.
$ref: '#/definitions/GeoJSONFeatureCollection'
BoundingBoxResponse:
description: This object is returned from a successful Spatial BoundingBox call.
type: object
properties:
summary:
description: Summary of the call.
type: object
readOnly: true
properties:
udid:
description: The udid for the user data if one exists
type: string
readOnly: true
information:
description: The information about what happened during the call.
type: string
readOnly: true
result:
description: The bounding box of the input feature collection.
type: object
readOnly: true
properties:
feature:
description: The resulting feature with bounding box geometry
type: object
readOnly: true
GetClosestPointResponse:
description: This object is returned from a successful Get Spatial Closest Point call
type: object
properties:
summary:
$ref: '#/definitions/GetClosestPointSummary'
result:
$ref: '#/definitions/ClosestPointResult'
PostClosestPointResponse:
description: This object is returned from a successful Post Spatial Closest Point call
type: object
properties:
summary:
$ref: '#/definitions/PostClosestPointSummary'
result:
$ref: '#/definitions/ClosestPointResult'
GetClosestPointSummary:
description: Get Closest Point Summary object
type: object
readOnly: true
properties:
sourcePoint:
$ref: '#/definitions/SpatialCoordinate'
udid:
description: A unique data id (udid) for the uploaded content
type: string
readOnly: true
information:
description: Processing information
type: string
readOnly: true
PostClosestPointSummary:
description: Post Closest Point Summary object
type: object
readOnly: true
properties:
sourcePoint:
$ref: '#/definitions/SpatialCoordinate'
udid:
description: >-
A unique data id (udid) for the uploaded content. Udid is not
applicable for POST spatial operations(set to null)
type: string
readOnly: true
information:
description: Processing information
type: string
readOnly: true
ClosestPointResult:
description: Closest Point Result Array
type: array
items:
$ref: '#/definitions/ClosestPointResultEntry'
ClosestPointResultEntry:
description: Closest Point Result Entry Object
type: object
readOnly: true
properties:
distanceInMeters:
description: The distance in meters from the source point to the closest point
type: number
readOnly: true
position:
$ref: '#/definitions/SpatialCoordinate'
geometryId:
description: The unique id identifies a geometry
type: string
readOnly: true
GetPointInPolygonResponse:
description: Returns true if point is within the polygon, false otherwise
type: object
properties:
summary:
$ref: '#/definitions/GetPointInPolygonSummary'
result:
$ref: '#/definitions/PointInPolygonResult'
PostPointInPolygonResponse:
description: Returns true if point is within the polygon, false otherwise
type: object
properties:
summary:
$ref: '#/definitions/PostPointInPolygonSummary'
result:
$ref: '#/definitions/PointInPolygonResult'
GetPointInPolygonSummary:
description: Point In Polygon Summary object
type: object
readOnly: true
properties:
sourcePoint:
$ref: '#/definitions/SpatialCoordinate'
udid:
description: A unique data id (udid) for the uploaded content
type: string
readOnly: true
information:
description: Processing information
type: string
readOnly: true
PostPointInPolygonSummary:
description: Point In Polygon Summary object
type: object
readOnly: true
properties:
sourcePoint:
$ref: '#/definitions/SpatialCoordinate'
udid:
description: >-
A unique data id (udid) for the uploaded content. Udid is not
applicable for POST spatial operations(set to null)
type: string
readOnly: true
information:
description: Processing information
type: string
readOnly: true
PointInPolygonResult:
description: Point In Polygon Result Object
type: object
properties:
pointInPolygons:
description: Point In Polygons Property
type: boolean
readOnly: true
intersectingGeometries:
description: Geometries array
type: array
readOnly: true
items:
$ref: '#/definitions/GeometryId'
GeometryId:
description: The Spatial geometry
type: string
readOnly: true
GreatCircleDistanceResponse:
description: This object is returned from a successful Great Circle Distance call
type: object
properties:
summary:
description: Summary object
type: object
readOnly: true
properties:
sourcePoint:
$ref: '#/definitions/SpatialCoordinate'
targetPoint:
$ref: '#/definitions/SpatialCoordinate'
result:
description: Result Object
type: object
readOnly: true
properties:
distanceInMeters:
description: >-
The great circle distance in meters from the source point to the
target point
type: number
readOnly: true
UploadDataRequestBody:
description: This type represents the request body for Spatial Data Upload.
type: object
UploadDataResponse:
description: >-
The response model for the spatial data upload API. Returns a unique data
id (udid) for the uploaded content.
type: object
properties:
udid:
description: A unique data id (udid) for the uploaded content.
type: string
readOnly: true
UploadDataAcceptedResponse:
description: >-
The response model for the spatial data upload API. Returns the current
status and a status URI.
type: object
properties:
status:
description: Current status of the long running upload operation.
type: string
readOnly: true
tags:
- name: Spatial