SpatialURL class
A SpatialURL represents a URL to the Azure Maps spatial operations.
- Extends
Constructors
| SpatialURL(Pipeline, string) | Creates an instance of SpatialURL. |
Inherited Properties
| maps |
Base URL string value. |
Methods
| get |
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 Otherwise uses the Get Buffer API: https://docs.microsoft.com/rest/api/maps/spatial/getbuffer |
| get |
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 Otherwise uses the Get Closest Point API: https://docs.microsoft.com/rest/api/maps/spatial/getclosestpoint |
| get |
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 codeIn geofencing response error contract, 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. |
| get |
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 |
| get |
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 Otherwise uses the Get Point In Polygon API: https://docs.microsoft.com/rest/api/maps/spatial/getpointinpolygon |
Inherited Methods
| new |
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.
Inherited Property Details
mapsUrl
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[]): Promise<GetBufferResponse>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
Promise<GetBufferResponse>
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): Promise<GetClosesPointResponse>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.
- options
- GetClosestPointOptions
Returns
Promise<GetClosesPointResponse>
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): Promise<GetGeofenceResponse>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.
- options
- GetGeofenceOptions
Returns
Promise<GetGeofenceResponse>
getGreatCircleDistance(Aborter, [GeoJSON.Position, GeoJSON.Position])
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: [GeoJSON.Position, GeoJSON.Position]): Promise<GetGreatCircleDistance>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
-
[GeoJSON.Position, GeoJSON.Position]
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
Promise<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
function getPointInPolygon(aborter: Aborter, udidOrFeatureCollection: string | SpatialFeatureCollection, position: GeoJSON.Position): Promise<GetPointInPolygonResponse>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
Promise<GetPointInPolygonResponse>
Inherited Method Details
newPipeline(Credential, INewPipelineOptions)
A static method used to create a new Pipeline object with Credential provided.
static function newPipeline(credential: Credential, pipelineOptions?: INewPipelineOptions): PipelineParameters
- credential
- Credential
Such as SubscriptionKeyCredential, TokenCredential, and MapControlCredential.
- pipelineOptions
- INewPipelineOptions
Returns
A new Pipeline object.
Inherited From MapsURL.newPipeline