SearchURL class
A SearchURL represents a URL to the Azure Maps search operations.
- Extends
SearchURL(Pipeline, string) | Creates an instance of SearchURL. |
maps |
Base URL string value. |
search |
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 |
search |
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 |
search |
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 |
search |
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 |
search |
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 |
search |
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.: |
search |
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 |
search |
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, Search |
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 |
search |
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 |
search |
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 |
new |
A static method used to create a new Pipeline object with Credential provided. |
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.
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>
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>
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]
.
Returns
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>
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
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>
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>
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").
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>
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>
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>
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>
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>
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
A new Pipeline object.
Inherited From MapsURL.newPipeline