SearchURL class

Package:

azure-maps-rest

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

Extends

MapsURL

Constructors

SearchURL(Pipeline, string)

Creates an instance of SearchURL.

Inherited Properties

mapsUrl

Base URL string value.

Methods

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

Inherited Methods

newPipeline(Credential, INewPipelineOptions)

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

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.

Inherited Property Details

mapsUrl

Base URL string value.

mapsUrl: string

Property Value

string

Inherited From MapsURL.mapsUrl

Method Details

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): Promise<SearchAddressResponse>

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").

options

SearchAddressOptions

Returns

Promise<SearchAddressResponse>

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): Promise<SearchAddressReverseResponse>

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].

options

SearchAddressReverseOptions

Returns

Promise<SearchAddressReverseResponse>

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): Promise<SearchAddressReverseCrossStreetResponse>

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].

options

SearchAddressReverseCrossStreetOptions

Returns

Promise<SearchAddressReverseCrossStreetResponse>

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): Promise<SearchAddressStructuredResponse>

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.

options

SearchAddressStructuredOptions

Returns

Promise<SearchAddressStructuredResponse>

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): Promise<SearchAlongRouteResponse>

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.

options

SearchAlongRouteOptions

Returns

Promise<SearchAlongRouteResponse>

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): Promise<SearchFuzzyResponse>

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]).

options

SearchFuzzyOptions

Returns

Promise<SearchFuzzyResponse>

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): Promise<SearchInsideGeometryResponse>

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.

options

SearchInsideGeometryOptions

Returns

Promise<SearchInsideGeometryResponse>

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): Promise<SearchNearbyResponse>

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].

options

SearchNearbyOptions

Returns

Promise<SearchNearbyResponse>

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): Promise<SearchPOIResponse>

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").

options

SearchPOIOptions

Returns

Promise<SearchPOIResponse>

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): Promise<SearchPOICategoryResponse>

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").

options

SearchPOICategoryOptions

Returns

Promise<SearchPOICategoryResponse>

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[]): Promise<SearchPolygonResponse>

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

Promise<SearchPolygonResponse>

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): Pipeline

Parameters

credential

Credential

Such as SubscriptionKeyCredential, TokenCredential, and MapControlCredential.

pipelineOptions

INewPipelineOptions

Returns

Pipeline

A new Pipeline object.

Inherited From MapsURL.newPipeline