SpatialURL class

A SpatialURL represents a URL to the Azure Maps spatial operations.

Extends

Constructors

SpatialURL(Pipeline, string)

Creates an instance of SpatialURL.

Properties

mapsUrl

Base URL string value.

Methods

getBuffer(Aborter, string | SpatialFeatureCollection, number[])

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 in the request or by a GeoJSON file which is uploaded via Data Upload API and referenced by a unique udid. The data may contain a collection of Point, MultiPoint, Polygon, MultiPolygon, LineString and MultiLineString. GeometryCollection will be ignored if provided. If directly providing the FeatureCollection uses the Post Buffer API: https://docs.microsoft.com/rest/api/maps/spatial/postbuffer

Otherwise uses the Get Buffer API: https://docs.microsoft.com/rest/api/maps/spatial/getbuffer

getClosestPoint(Aborter, GeoJSON.Position, string | SpatialFeatureCollection, GetClosestPointOptions)

Returns the closest point between a base point and a given set of points provided by user data in the request or in a user uploaded data set identified by udid. If using a udid the set of target points is provided by a GeoJSON file which is uploaded via Data Upload API 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. If directly providing the FeatureCollection uses the Post Closest Point API: https://docs.microsoft.com/rest/api/maps/spatial/postclosestpoint

Otherwise uses the Get Closest Point API: https://docs.microsoft.com/rest/api/maps/spatial/getclosestpoint

getGeofence(Aborter, string, string | SpatialFeatureCollection, GeoJSON.Position, GetGeofenceOptions)

Retrieves the proximity of a coordinate to a geofence provided in the request or that has been uploaded to the Data service. You can use the Data Upload API to upload a geofence or set of fences. See Geofencing GeoJSON data 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. 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.

If directly providing the geofence uses the Post Geofence API: https://docs.microsoft.com/rest/api/maps/spatial/postgeofence

Otherwise uses the Get Geofence API: https://docs.microsoft.com/en-us/rest/api/maps/spatial/getgeofence

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 | 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| Can't find user geofencing data with provided udId.

getGreatCircleDistance(Aborter, Object)

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. Uses the Get Great Circle Distance API: https://docs.microsoft.com/rest/api/maps/spatial/getgreatcircledistance

getPointInPolygon(Aborter, string | SpatialFeatureCollection, GeoJSON.Position)

Returns whether a point is inside a set of polygons. The set of polygons is provided in the request or by a GeoJSON file which is uploaded via Data Upload API 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. If directly providing the FeatureCollection uses the Post Point In Polygon API: https://docs.microsoft.com/rest/api/maps/spatial/postpointinpolygon

Otherwise uses the Get Point In Polygon API: https://docs.microsoft.com/rest/api/maps/spatial/getpointinpolygon

newPipeline(Credential, INewPipelineOptions)

A static method used to create a new Pipeline object with Credential provided.

Constructor Details

SpatialURL(Pipeline, string)

Creates an instance of SpatialURL.

new SpatialURL(pipeline: Pipeline, mapsUrl?: string)

Parameters

pipeline
Pipeline

Call MapsURL.newPipeline() to create a default pipeline, or provide a customized pipeline.

mapsUrl
string

A URL string pointing to Azure Maps service, default is "https://atlas.microsoft.com". If no protocol is specified, e.g. "atlas.microsoft.com", then https will be assumed.

Property Details

mapsUrl

Base URL string value.

mapsUrl: string

Property Value

string

Method Details

getBuffer(Aborter, string | SpatialFeatureCollection, number[])

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 in the request or by a GeoJSON file which is uploaded via Data Upload API and referenced by a unique udid. The data may contain a collection of Point, MultiPoint, Polygon, MultiPolygon, LineString and MultiLineString. GeometryCollection will be ignored if provided. If directly providing the FeatureCollection uses the Post Buffer API: https://docs.microsoft.com/rest/api/maps/spatial/postbuffer

Otherwise uses the Get Buffer API: https://docs.microsoft.com/rest/api/maps/spatial/getbuffer

function getBuffer(aborter: Aborter, udidOrFeatureCollection: string | SpatialFeatureCollection, distances: number[])

Parameters

aborter
Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation.

udidOrFeatureCollection
string | SpatialFeatureCollection

A FeatureCollection containing the inputs or 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.

distances
number[]

The list of distances (one per feature or one for all features). 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.

Returns

getClosestPoint(Aborter, GeoJSON.Position, string | SpatialFeatureCollection, GetClosestPointOptions)

Returns the closest point between a base point and a given set of points provided by user data in the request or in a user uploaded data set identified by udid. If using a udid the set of target points is provided by a GeoJSON file which is uploaded via Data Upload API 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. If directly providing the FeatureCollection uses the Post Closest Point API: https://docs.microsoft.com/rest/api/maps/spatial/postclosestpoint

Otherwise uses the Get Closest Point API: https://docs.microsoft.com/rest/api/maps/spatial/getclosestpoint

function getClosestPoint(aborter: Aborter, position: GeoJSON.Position, udidOrFeatureCollection: string | SpatialFeatureCollection, options?: GetClosestPointOptions)

Parameters

aborter
Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation.

position
GeoJSON.Position

The base point.

udidOrFeatureCollection
string | SpatialFeatureCollection

A FeatureCollection containing the target points or 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.

Returns

getGeofence(Aborter, string, string | SpatialFeatureCollection, GeoJSON.Position, GetGeofenceOptions)

Retrieves the proximity of a coordinate to a geofence provided in the request or that has been uploaded to the Data service. You can use the Data Upload API to upload a geofence or set of fences. See Geofencing GeoJSON data 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. 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.

If directly providing the geofence uses the Post Geofence API: https://docs.microsoft.com/rest/api/maps/spatial/postgeofence

Otherwise uses the Get Geofence API: https://docs.microsoft.com/en-us/rest/api/maps/spatial/getgeofence

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 | 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| Can't find user geofencing data with provided udId.

function getGeofence(aborter: Aborter, deviceId: string, udidOrFeatureCollection: string | SpatialFeatureCollection, position: GeoJSON.Position, options?: GetGeofenceOptions)

Parameters

aborter
Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation.

deviceId
string

ID of the device

udidOrFeatureCollection
string | SpatialFeatureCollection

A FeatureCollection containing the fence or 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.

position
GeoJSON.Position

The location being passed.

Returns

getGreatCircleDistance(Aborter, Object)

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. Uses the Get Great Circle Distance API: https://docs.microsoft.com/rest/api/maps/spatial/getgreatcircledistance

function getGreatCircleDistance(aborter: Aborter, coordinates: Object)

Parameters

aborter
Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation.

coordinates
Object

The coordinates through which the distance is calculated. Two coordinates are required. The first one is the source point coordinate and the last is the target point coordinate.

Returns

getPointInPolygon(Aborter, string | SpatialFeatureCollection, GeoJSON.Position)

Returns whether a point is inside a set of polygons. The set of polygons is provided in the request or by a GeoJSON file which is uploaded via Data Upload API 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. If directly providing the FeatureCollection uses the Post Point In Polygon API: https://docs.microsoft.com/rest/api/maps/spatial/postpointinpolygon

Otherwise uses the Get Point In Polygon API: https://docs.microsoft.com/rest/api/maps/spatial/getpointinpolygon

function getPointInPolygon(aborter: Aborter, udidOrFeatureCollection: string | SpatialFeatureCollection, position: GeoJSON.Position)

Parameters

aborter
Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation.

udidOrFeatureCollection
string | SpatialFeatureCollection

A FeatureCollection containing the polygons or 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.

position
GeoJSON.Position

The base point.

Returns

newPipeline(Credential, INewPipelineOptions)

A static method used to create a new Pipeline object with Credential provided.

static function newPipeline(credential: Credential, pipelineOptions?: INewPipelineOptions)

Parameters

credential
Credential

Such as SubscriptionKeyCredential, TokenCredential, and MapControlCredential.

pipelineOptions
INewPipelineOptions

Returns

A new Pipeline object.