SearchURL class

A SearchURL represents a URL to the Azure Maps search operations.

Extends

Constructors

SearchURL(Pipeline, string)

Creates an instance of SearchURL.

Properties

mapsUrl

Base URL string value.

Methods

newPipeline(Credential, INewPipelineOptions)

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

searchAddress(Aborter, string, SearchAddressOptions)

Address Geocoding In many cases, the complete search service might be too much, for instance if you are only interested in traditional geocoding. Search can also be accessed for address look up exclusively. The geocoding is performed by hitting the geocode endpoint with just the address or partial address in question. The geocoding search index will be queried for everything above the street level data. No POIs will be returned. Note that the geocoder is very tolerant of typos and incomplete addresses. It will also handle everything from exact street addresses or street or intersections as well as higher level geographies such as city centers, counties, states etc. Uses the Get Search Address API: https://docs.microsoft.com/rest/api/maps/search/getsearchaddress

searchAddressReverse(Aborter, GeoJSON.Position, SearchAddressReverseOptions)

Reverse Geocode to an Address There may be times when you need to translate a coordinate (example: -122.3862, 37.786505) into a human understandable street address. Most often this is needed in tracking applications where you receive a GPS feed from the device or asset and wish to know what address where the coordinate is located. This endpoint will return address information for a given coordinate. Uses the Get Search Address Reverse API: https://docs.microsoft.com/rest/api/maps/search/getsearchaddressreverse

searchAddressReverseCrossStreet(Aborter, GeoJSON.Position, SearchAddressReverseCrossStreetOptions)

Reverse Geocode to a Cross Street There may be times when you need to translate a coordinate (example: -122.3862, 37.786505) into a human understandable cross street. Most often this is needed in tracking applications where you receive a GPS feed from the device or asset and wish to know what address where the coordinate is located. This endpoint will return cross street information for a given coordinate. Uses the Get Search Address Reverse Cross Street API: https://docs.microsoft.com/rest/api/maps/search/getsearchaddressreversecrossstreet

searchAddressStructured(Aborter, string, SearchAddressStructuredOptions)

Structured Address Geocoding Azure Address Geocoding can also be accessed for structured address look up exclusively. The geocoding search index will be queried for everything above the street level data. No POIs will be returned. Note that the geocoder is very tolerant of typos and incomplete addresses. It will also handle everything from exact street addresses or street or intersections as well as higher level geographies such as city centers, counties, states etc. Uses the Get Search Address Structured API: https://docs.microsoft.com/rest/api/maps/search/getsearchaddressstructured

searchAlongRoute(Aborter, string, number, SearchAlongRouteRequestBody, SearchAlongRouteOptions)

The Search Along Route endpoint allows you to perform a fuzzy search for POIs along a specified route. This search is constrained by specifying the maxDetourTime limiting measure. To send the route-points you will use a body which will contain the route object represented as a GeoJSON LineString type and the Content-Type header will be set to application/json. Each route-point in route is represented as a GeoJSON Position type i.e. an array where the longitude value is followed by the latitude value and the altitude value is ignored. The route should contain at least 2 route-points. It is possible that original route will be altered, some of it's points may be skipped. If the route that passes through the found point is faster than the original one, the detourTime value in the response is negative. Uses the Post Search Along Route API: https://docs.microsoft.com/rest/api/maps/search/postsearchalongroute

searchFuzzy(Aborter, string | GeoJSON.Position, SearchFuzzyOptions)

Free Form Search The basic default API is Free Form Search which handles the most fuzzy of inputs handling any combination of address or POI tokens. This search API is the canonical 'single line search'. The Free Form Search API is a seamless combination of POI search and geocoding. The API can also be weighted with a contextual position (lat./lon. pair), or fully constrained by a coordinate and radius, or it can be executed more generally without any geo biasing anchor point. We strongly advise you to use the 'countrySet' parameter to specify only the countries for which your application needs coverage, as the default behavior will be to search the entire world, potentially returning unnecessary results. E.g.: countrySet=US,FR. Please see [Search Coverage] (https://docs.microsoft.com/azure/location-based-services/geocoding-coverage) for a complete list of all the supported countries. Most Search queries default to maxFuzzyLevel=2 to gain performance and also reduce unusual results. This new default can be overridden as needed per request by passing in the query param maxFuzzyLevel=3 or 4. Uses the Get Search Fuzzy API: https://docs.microsoft.com/rest/api/maps/search/getsearchfuzzy

searchInsideGeometry(Aborter, string, SearchInsideGeometryRequestBody, SearchInsideGeometryOptions)

The Search Geometry endpoint allows you to perform a free form search inside a single geometry or many of them. The search results that fall inside the geometry/geometries will be returned. The geographical features to be searched can be modeled as Polygon and/or Circle geometries represented using any one of the following GeoJSON types: GeoJSON FeatureCollection, The geometry can be represented as a GeoJSON FeatureCollection object. This is the recommended option if the geometry contains both Polygons and Circles. The FeatureCollection can contain a max of 50 GeoJSON Feature objects. Each Feature object should represent either a Polygon or a Circle with the following conditions: A Feature object for the Polygon geometry can have a max of 50 coordinates and it's properties must be empty. A Feature object for the Circle geometry is composed of a center represented using a GeoJSON Point type and a radius value (in meters) which must be specified in the object's properties along with the subType property whose value should be 'Circle'. Please see the Examples section below for a sample FeatureCollection representation. GeoJSON GeometryCollection, The geometry can be represented as a GeoJSON GeometryCollection object. This is the recommended option if the geometry contains a list of Polygons only. The GeometryCollection can contain a max of 50 GeoJSON Polygon objects. Each Polygon object can have a max of 50 coordinates. Please see the Examples section below for a sample GeometryCollection representation. GeoJSON Polygon, The geometry can be represented as a GeoJSON Polygon object. This is the recommended option if the geometry contains a single Polygon. The Polygon object can have a max of 50 coordinates. Uses the Post Search Inside Geometry API: https://docs.microsoft.com/rest/api/maps/search/postsearchinsidegeometry

searchNearby(Aborter, GeoJSON.Position, SearchNearbyOptions)

Nearby Search If you have a use case for only retrieving POI results around a specific location, the nearby search method may be the right choice. This endpoint will only return POI results, and does not take in a search query parameter. Uses the Get Search Nearby API: https://docs.microsoft.com/rest/api/maps/search/getsearchnearby

searchPOI(Aborter, string, SearchPOIOptions)

Get POI by Name If your search use case only requires POI results, you may use the POI endpoint for searching. This endpoint will only return POI results. Uses the Get Search POI API: https://docs.microsoft.com/rest/api/maps/search/getsearchpoi

searchPOICategory(Aborter, string, SearchPOICategoryOptions)

Get POI by Category If your search use case only requires POI results filtered by category, you may use the category endpoint. This endpoint will only return POI results which are categorized as specified. List of available categories can be found here. Uses the Get Search POI Category API: https://docs.microsoft.com/rest/api/maps/search/getsearchpoicategory

searchPolygon(Aborter, string[])

The Search Polygon API allows you to request the geometry data such as a city or country outline for a set of entities, previously retrieved from an Online Search request in GeoJSON format. The geometry ID is returned in the dataSources object under "geometry" and "id" in either a Search Address or Search Fuzzy call. Please note that any geometry ID retrieved from an Online Search endpoint has a limited lifetime. The client should not store geometry IDs in persistent storage for later referral, as the stability of these identifiers is not guaranteed for a long period of time. It is expected that a request to the Polygon method is made within a few minutes of the request to the Online Search method that provided the ID. The service allows for batch requests up to 20 identifiers.

Uses the Get Search Polygon API: https://docs.microsoft.com/rest/api/maps/search/getsearchpolygon

Constructor Details

SearchURL(Pipeline, string)

Creates an instance of SearchURL.

new SearchURL(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

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.

searchAddress(Aborter, string, SearchAddressOptions)

Address Geocoding In many cases, the complete search service might be too much, for instance if you are only interested in traditional geocoding. Search can also be accessed for address look up exclusively. The geocoding is performed by hitting the geocode endpoint with just the address or partial address in question. The geocoding search index will be queried for everything above the street level data. No POIs will be returned. Note that the geocoder is very tolerant of typos and incomplete addresses. It will also handle everything from exact street addresses or street or intersections as well as higher level geographies such as city centers, counties, states etc. Uses the Get Search Address API: https://docs.microsoft.com/rest/api/maps/search/getsearchaddress

function searchAddress(aborter: Aborter, query: string, options?: SearchAddressOptions)

Parameters

aborter
Aborter

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

query
string

The address to search for (e.g., "1 Microsoft way, Redmond, WA").

Returns

searchAddressReverse(Aborter, GeoJSON.Position, SearchAddressReverseOptions)

Reverse Geocode to an Address There may be times when you need to translate a coordinate (example: -122.3862, 37.786505) into a human understandable street address. Most often this is needed in tracking applications where you receive a GPS feed from the device or asset and wish to know what address where the coordinate is located. This endpoint will return address information for a given coordinate. Uses the Get Search Address Reverse API: https://docs.microsoft.com/rest/api/maps/search/getsearchaddressreverse

function searchAddressReverse(aborter: Aborter, position: GeoJSON.Position, options?: SearchAddressReverseOptions)

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 position to reverse search, a coordinate array of [longitude, latitude] e.g. [-122.125679, 47.641268].

Returns

searchAddressReverseCrossStreet(Aborter, GeoJSON.Position, SearchAddressReverseCrossStreetOptions)

Reverse Geocode to a Cross Street There may be times when you need to translate a coordinate (example: -122.3862, 37.786505) into a human understandable cross street. Most often this is needed in tracking applications where you receive a GPS feed from the device or asset and wish to know what address where the coordinate is located. This endpoint will return cross street information for a given coordinate. Uses the Get Search Address Reverse Cross Street API: https://docs.microsoft.com/rest/api/maps/search/getsearchaddressreversecrossstreet

function searchAddressReverseCrossStreet(aborter: Aborter, position: GeoJSON.Position, options?: SearchAddressReverseCrossStreetOptions)

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 position to reverse search, a coordinate array of [longitude, latitude] e.g. [-122.125679, 47.641268].

Returns

searchAddressStructured(Aborter, string, SearchAddressStructuredOptions)

Structured Address Geocoding Azure Address Geocoding can also be accessed for structured address look up exclusively. The geocoding search index will be queried for everything above the street level data. No POIs will be returned. Note that the geocoder is very tolerant of typos and incomplete addresses. It will also handle everything from exact street addresses or street or intersections as well as higher level geographies such as city centers, counties, states etc. Uses the Get Search Address Structured API: https://docs.microsoft.com/rest/api/maps/search/getsearchaddressstructured

function searchAddressStructured(aborter: Aborter, countryCode: string, options?: SearchAddressStructuredOptions)

Parameters

aborter
Aborter

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

countryCode
string

The 2 or 3 letter ISO3166-1 country code portion of an address. E.g. US.

Returns

searchAlongRoute(Aborter, string, number, SearchAlongRouteRequestBody, SearchAlongRouteOptions)

The Search Along Route endpoint allows you to perform a fuzzy search for POIs along a specified route. This search is constrained by specifying the maxDetourTime limiting measure. To send the route-points you will use a body which will contain the route object represented as a GeoJSON LineString type and the Content-Type header will be set to application/json. Each route-point in route is represented as a GeoJSON Position type i.e. an array where the longitude value is followed by the latitude value and the altitude value is ignored. The route should contain at least 2 route-points. It is possible that original route will be altered, some of it's points may be skipped. If the route that passes through the found point is faster than the original one, the detourTime value in the response is negative. Uses the Post Search Along Route API: https://docs.microsoft.com/rest/api/maps/search/postsearchalongroute

function searchAlongRoute(aborter: Aborter, query: string, maxDetourTime: number, body: SearchAlongRouteRequestBody, options?: SearchAlongRouteOptions)

Parameters

aborter
Aborter

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

query
string

The applicable query string (e.g., "seattle", "pizza").

maxDetourTime
number

Maximum detour time of the point of interest in seconds. Max value is 3600 seconds

body
SearchAlongRouteRequestBody

This represents the route to search along and should be a valid GeoJSON LineString type. Please refer to RFC 7946 for details.

Returns

searchFuzzy(Aborter, string | GeoJSON.Position, SearchFuzzyOptions)

Free Form Search The basic default API is Free Form Search which handles the most fuzzy of inputs handling any combination of address or POI tokens. This search API is the canonical 'single line search'. The Free Form Search API is a seamless combination of POI search and geocoding. The API can also be weighted with a contextual position (lat./lon. pair), or fully constrained by a coordinate and radius, or it can be executed more generally without any geo biasing anchor point. We strongly advise you to use the 'countrySet' parameter to specify only the countries for which your application needs coverage, as the default behavior will be to search the entire world, potentially returning unnecessary results. E.g.: countrySet=US,FR. Please see [Search Coverage] (https://docs.microsoft.com/azure/location-based-services/geocoding-coverage) for a complete list of all the supported countries. Most Search queries default to maxFuzzyLevel=2 to gain performance and also reduce unusual results. This new default can be overridden as needed per request by passing in the query param maxFuzzyLevel=3 or 4. Uses the Get Search Fuzzy API: https://docs.microsoft.com/rest/api/maps/search/getsearchfuzzy

function searchFuzzy(aborter: Aborter, query: string | GeoJSON.Position, options?: SearchFuzzyOptions)

Parameters

aborter
Aborter

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

query
string | GeoJSON.Position

The applicable query string (e.g., "seattle", "pizza"). Can also be specified as a coordinate array of [longitude, latitude] (e.g., [-122.125679, 47.641268]).

Returns

searchInsideGeometry(Aborter, string, SearchInsideGeometryRequestBody, SearchInsideGeometryOptions)

The Search Geometry endpoint allows you to perform a free form search inside a single geometry or many of them. The search results that fall inside the geometry/geometries will be returned. The geographical features to be searched can be modeled as Polygon and/or Circle geometries represented using any one of the following GeoJSON types: GeoJSON FeatureCollection, The geometry can be represented as a GeoJSON FeatureCollection object. This is the recommended option if the geometry contains both Polygons and Circles. The FeatureCollection can contain a max of 50 GeoJSON Feature objects. Each Feature object should represent either a Polygon or a Circle with the following conditions: A Feature object for the Polygon geometry can have a max of 50 coordinates and it's properties must be empty. A Feature object for the Circle geometry is composed of a center represented using a GeoJSON Point type and a radius value (in meters) which must be specified in the object's properties along with the subType property whose value should be 'Circle'. Please see the Examples section below for a sample FeatureCollection representation. GeoJSON GeometryCollection, The geometry can be represented as a GeoJSON GeometryCollection object. This is the recommended option if the geometry contains a list of Polygons only. The GeometryCollection can contain a max of 50 GeoJSON Polygon objects. Each Polygon object can have a max of 50 coordinates. Please see the Examples section below for a sample GeometryCollection representation. GeoJSON Polygon, The geometry can be represented as a GeoJSON Polygon object. This is the recommended option if the geometry contains a single Polygon. The Polygon object can have a max of 50 coordinates. Uses the Post Search Inside Geometry API: https://docs.microsoft.com/rest/api/maps/search/postsearchinsidegeometry

function searchInsideGeometry(aborter: Aborter, query: string, body: SearchInsideGeometryRequestBody, options?: SearchInsideGeometryOptions)

Parameters

aborter
Aborter

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

query
string

The applicable query string (e.g., "seattle", "pizza").

body
SearchInsideGeometryRequestBody

This represents the geometry for one or more geographical features (parks, state boundary etc.) to search in and should be a GeoJSON compliant type. Please refer to RFC 7946 for details.

Returns

searchNearby(Aborter, GeoJSON.Position, SearchNearbyOptions)

Nearby Search If you have a use case for only retrieving POI results around a specific location, the nearby search method may be the right choice. This endpoint will only return POI results, and does not take in a search query parameter. Uses the Get Search Nearby API: https://docs.microsoft.com/rest/api/maps/search/getsearchnearby

function searchNearby(aborter: Aborter, location: GeoJSON.Position, options?: SearchNearbyOptions)

Parameters

aborter
Aborter

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

location
GeoJSON.Position

Location where results should be biased. Should be an array of [longitude, latitude], E.g. [-121.89, 37.337].

Returns

searchPOI(Aborter, string, SearchPOIOptions)

Get POI by Name If your search use case only requires POI results, you may use the POI endpoint for searching. This endpoint will only return POI results. Uses the Get Search POI API: https://docs.microsoft.com/rest/api/maps/search/getsearchpoi

function searchPOI(aborter: Aborter, query: string, options?: SearchPOIOptions)

Parameters

aborter
Aborter

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

query
string

The POI name to search for (e.g., "statue of liberty", "starbucks").

Returns

searchPOICategory(Aborter, string, SearchPOICategoryOptions)

Get POI by Category If your search use case only requires POI results filtered by category, you may use the category endpoint. This endpoint will only return POI results which are categorized as specified. List of available categories can be found here. Uses the Get Search POI Category API: https://docs.microsoft.com/rest/api/maps/search/getsearchpoicategory

function searchPOICategory(aborter: Aborter, query: string, options?: SearchPOICategoryOptions)

Parameters

aborter
Aborter

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

query
string

The POI category to search for (e.g., "AIRPORT", "BEACH").

Returns

searchPolygon(Aborter, string[])

The Search Polygon API allows you to request the geometry data such as a city or country outline for a set of entities, previously retrieved from an Online Search request in GeoJSON format. The geometry ID is returned in the dataSources object under "geometry" and "id" in either a Search Address or Search Fuzzy call. Please note that any geometry ID retrieved from an Online Search endpoint has a limited lifetime. The client should not store geometry IDs in persistent storage for later referral, as the stability of these identifiers is not guaranteed for a long period of time. It is expected that a request to the Polygon method is made within a few minutes of the request to the Online Search method that provided the ID. The service allows for batch requests up to 20 identifiers.

Uses the Get Search Polygon API: https://docs.microsoft.com/rest/api/maps/search/getsearchpolygon

function searchPolygon(aborter: Aborter, geometries: string[])

Parameters

aborter
Aborter

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

geometries
string[]

Comma separated list of geometry UUIDs, previously retrieved from an Online Search request.

Returns