Search

Operations

Get Search Address

Address Geocoding

Applies to: S0 and S1 pricing tiers.

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.

Get Search Address Reverse

Reverse Geocode to an Address

Applies to: S0 and S1 pricing tiers.

There may be times when you need to translate a coordinate (example: 37.786505, -122.3862) 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.

Get Search Address Reverse Cross Street

Reverse Geocode to a Cross Street

Applies to: S0 and S1 pricing tiers.

There may be times when you need to translate a coordinate (example: 37.786505, -122.3862) 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.

Get Search Address Structured

Structured Address Geocoding

Applies to: S0 and S1 pricing tiers.

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.

Get Search Fuzzy

Free Form Search

Applies to: S0 and S1 pricing tiers.

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

Get Search Nearby

Nearby Search

Applies to: S0 and S1 pricing tiers.

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.

Get Search POI

Get POI by Name

Applies to: S0 and S1 pricing tiers.

Points of Interest (POI) Search allows you to request POI results by name. Search supports additional query parameters such as language and filtering results by area of interest driven by country or bounding box. Endpoint will return only POI results matching the query string. Response includes POI details such as address, coordinate location and category.

Get Search POI Category

Get POI by Category

Applies to: S0 and S1 pricing tiers.

Points of Interest (POI) Category Search allows you to request POI results from given category. Search allows to query POIs from one category at a time. Endpoint will only return POI results which are categorized as specified. Response includes POI details such as address, coordinate location and category.

List of available categories can be found here.

Get Search Polygon

Get Polygon

Applies to: S1 pricing tier.

The Get Polygon service 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.

Post Search Address Batch Preview

Search Address Batch API

Applies to: S1 pricing tier.

The Search Address Batch API allows the caller to batch up to 10,000 Search Address API queries/requests using just a single API call.

Submit Batch Request

To send the search address queries you will use a POST request where the request body will contain the queries array in json format and the Content-Type header will be set to application/json. Here's a sample request body containing 5 search address queries:

{
    "queries": [
        "?query=400 Broad St, Seattle, WA 98109&limit=3",
        "?query=One, Microsoft Way, Redmond, WA 98052&limit=3",
        "?query=350 5th Ave, New York, NY 10118&limit=1",
        "?query=Pike Pl, Seattle, WA 98101&lat=47.610970&lon=-122.342469&radius=1000",
        "?query=Champ de Mars, 5 Avenue Anatole France, 75007 Paris, France&limit=1"
    ]
}


A search address query in a batch is just a partial URL without the protocol, base URL, path, api-version and subscription-key. It can accept any of the supported search address URI parameters. The string values in the search address query must be properly escaped (e.g. " character should be escaped with \ ) and it should also be properly URL-encoded.

The maximum number of queries that can be specified in the batch is 10,000 and the batch should contain at least 1 query.

Please note that the Search Address Batch API is a long-running request. Here's a typical sequence of operations:

  1. Client sends a Search Address Batch POST request to Azure Maps
  2. The server will respond with one of the following:

    HTTP 202 Accepted - Batch request has been accepted.

    HTTP Error - There was an error processing your Batch request. This could either be a 400 Bad Request or any other Error status code.

  3. If the batch request was accepted successfully, the Location header in the response contains the URL to download the results of the batch request.

  4. Client issues a GET request on the download URL obtained in Step 3 to download the batch results.


Download Batch Results

To download the batch results you will issue a GET request to the batch download endpoint. This download URL can be obtained from the Location header of a successful POST batch request and looks like the following:

https://atlas.microsoft.com/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}


Here's the typical sequence of operations for downloading the batch results:

  1. Client sends a GET request using the download URL.
  2. The server will respond with one of the following:

    HTTP 202 Accepted - Batch request was accepted but is still being processed. Please try again in some time.

    HTTP 200 OK - Batch request successfully processed. The response body contains all the batch results.


Batch Response Model

When downloading the results of a batch request, if the batch has finished processing, the response body contains the batch response. This batch response contains a summary component that indicates the totalRequests that were part of the original batch request and successfulRequests i.e. queries which were executed successfully. The batch response also includes a batchResults array which contains a response for each and every query in the batch request. Also, the batchResults will contain the results in the exact same order the original queries were sent in the batch request. Each entry in batchResults is of one of the following types:

  • SearchAddressResponse - If the query completed successfully.

  • Error - If the query failed. The result will contain a status code and a message in this case.


Here's a sample Batch Response with 2 successful and 1 failed result:

{
    "summary": {
        "successfulRequests": 2,
        "totalRequests": 3
    },
    "batchResults": [
        {
            "summary": {
                "query": "one microsoft way redmond wa 98052"
            },
            "results": [
                {
                    "position": {
                        "lat": 47.63989,
                        "lon": -122.12509
                    }
                }
            ]
        },
        {
            "summary": {
                "query": "pike pl seattle wa 98101"
            },
            "results": [
                {
                    "position": {
                        "lat": 47.60963,
                        "lon": -122.34215
                    }
                }
            ]
        },
        {
            "statusCode": 400,
            "message": "Bad Request"
        }
    ]
}


Data Retention Period

Please, be aware that batch results are available for download for 14 days, after which the request for results download will return 400 Bad Request response.

Post Search Address Reverse Batch Preview

Search Address Reverse Batch API

Applies to: S1 pricing tier.

The Search Address Reverse Batch API allows the caller to batch up to 10,000 Search Address Reverse API queries/requests using just a single API call.

Submit Batch Request

To send the search address reverse queries you will use a POST request where the request body will contain the queries array in json format and the Content-Type header will be set to application/json. Here's a sample request body containing 5 search address reverse queries:

{
    "queries": [
        "?query=48.858561,2.294911",
        "?query=47.639765,-122.127896&radius=5000&limit=2",
        "?query=47.621028,-122.348170",
        "?query=43.722990,10.396695",
        "?query=40.750958,-73.982336"
    ]
}


A search address reverse query in a batch is just a partial URL without the protocol, base URL, path, api-version and subscription-key. It can accept any of the supported search address reverse URI parameters. The string values in the search address reverse query must be properly escaped (e.g. " character should be escaped with \ ) and it should also be properly URL-encoded.

The maximum number of queries that can be specified in the batch is 10,000 and the batch should contain at least 1 query.

Please note that the Search Address Reverse Batch API is a long-running request. Here's a typical sequence of operations:

  1. Client sends a Search Address Reverse Batch POST request to Azure Maps
  2. The server will respond with one of the following:

    HTTP 202 Accepted - Batch request has been accepted.

    HTTP Error - There was an error processing your Batch request. This could either be a 400 Bad Request or any other Error status code.

  3. If the batch request was accepted successfully, the Location header in the response contains the URL to download the results of the batch request.

  4. Client issues a GET request on the download URL obtained in Step 3 to download the batch results.


Download Batch Results

To download the batch results you will issue a GET request to the batch download endpoint. This download URL can be obtained from the Location header of a successful POST batch request and looks like the following:

https://atlas.microsoft.com/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}


Here's the typical sequence of operations for downloading the batch results:

  1. Client sends a GET request using the download URL.
  2. The server will respond with one of the following:

    HTTP 202 Accepted - Batch request was accepted but is still being processed. Please try again in some time.

    HTTP 200 OK - Batch request successfully processed. The response body contains all the batch results.


Batch Response Model

When downloading the results of a batch request, if the batch has finished processing, the response body contains the batch response. This batch response contains a summary component that indicates the totalRequests that were part of the original batch request and successfulRequests i.e. queries which were executed successfully. The batch response also includes a batchResults array which contains a response for each and every query in the batch request. Also, the batchResults will contain the results in the exact same order the original queries were sent in the batch request. Each entry in batchResults is of one of the following types:

  • SearchAddressReverseResponse - If the query completed successfully.

  • Error - If the query failed. The result will contain a status code and a message in this case.


Here's a sample Batch Response with 2 successful and 1 failed result:

{
    "summary": {
        "successfulRequests": 2,
        "totalRequests": 3
    },
    "batchResults": [
        {
            "summary": {
                "queryTime": 11
            },
            "addresses": [
                {
                    "address": {
                        "country": "France",
                        "freeformAddress": "Avenue Anatole France, 75007 Paris"
                    },
                    "position": "48.858490,2.294820"
                }
            ]
        },
        {
            "summary": {
                "queryTime": 1
            },
            "addresses": [
                {
                    "address": {
                        "country": "United States of America",
                        "freeformAddress": "157th Pl NE, Redmond WA 98052"
                    },
                    "position": "47.640470,-122.129430"
                }
            ]
        },
        {
            "statusCode": 400,
            "message": "Bad Request"
        }
    ]
}


Data Retention Period

Please, be aware that batch results are available for download for 14 days, after which the request for results download will return 400 Bad Request response.

Post Search Along Route

Applies to: S0 and S1 pricing tiers.

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 POST request where the request body 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.

Post Search Fuzzy Batch Preview

Search Fuzzy Batch API

Applies to: S1 pricing tier.

The Search Fuzzy Batch API allows the caller to batch up to 10,000 Search Fuzzy API queries/requests using just a single API call.

Submit Batch Request

To send the search fuzzy queries you will use a POST request where the request body will contain the queries array in json format and the Content-Type header will be set to application/json. Here's a sample request body containing 5 search fuzzy queries:

{
    "queries": [
        "?query=atm&lat=47.639769&lon=-122.128362&radius=5000&limit=5",
        "?query=Statue Of Liberty&limit=2",
        "?query=Starbucks&lat=47.639769&lon=-122.128362&radius=5000",
        "?query=Space Needle",
        "?query=pizza&limit=10"
    ]
}


A search fuzzy query in a batch is just a partial URL without the protocol, base URL, path, api-version and subscription-key. It can accept any of the supported search fuzzy URI parameters. The string values in the search fuzzy query must be properly escaped (e.g. " character should be escaped with \ ) and it should also be properly URL-encoded.

The maximum number of queries that can be specified in the batch is 10,000 and the batch should contain at least 1 query.

Please note that the Search Fuzzy Batch API is a long-running request. Here's a typical sequence of operations:

  1. Client sends a Search Fuzzy Batch POST request to Azure Maps
  2. The server will respond with one of the following:

    HTTP 202 Accepted - Batch request has been accepted.

    HTTP Error - There was an error processing your Batch request. This could either be a 400 Bad Request or any other Error status code.

  3. If the batch request was accepted successfully, the Location header in the response contains the URL to download the results of the batch request.

  4. Client issues a GET request on the download URL obtained in Step 3 to download the batch results.


Download Batch Results

To download the batch results you will issue a GET request to the batch download endpoint. This download URL can be obtained from the Location header of a successful POST batch request and looks like the following:

https://atlas.microsoft.com/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}    


Here's the typical sequence of operations for downloading the batch results:

  1. Client sends a GET request using the download URL.
  2. The server will respond with one of the following:

    HTTP 202 Accepted - Batch request was accepted but is still being processed. Please try again in some time.

    HTTP 200 OK - Batch request successfully processed. The response body contains all the batch results.


Batch Response Model

When downloading the results of a batch request, if the batch has finished processing, the response body contains the batch response. This batch response contains a summary component that indicates the totalRequests that were part of the original batch request and successfulRequests i.e. queries which were executed successfully. The batch response also includes a batchResults array which contains a response for each and every query in the batch request. Also, the batchResults will contain the results in the exact same order the original queries were sent in the batch request. Each entry in batchResults is of one of the following types:

  • SearchFuzzyResponse - If the query completed successfully.

  • Error - If the query failed. The result will contain a status code and a message in this case.


Here's a sample Batch Response with 2 successful and 1 failed result:

{
    "summary": {
        "successfulRequests": 2,
        "totalRequests": 3
    },
    "batchResults": [
        {
            "summary": {
                "query": "atm"
            },
            "results": [
                {
                    "type": "POI",
                    "poi": {
                        "name": "ATM at Wells Fargo"
                    },
                    "address": {
                        "country": "United States Of America",
                        "freeformAddress": "3240 157th Ave NE, Redmond, WA 98052"
                    }
                }
            ]
        },
        {
            "summary": {
                "query": "statue of liberty"
            },
            "results": [
                {
                    "type": "POI",
                    "poi": {
                        "name": "Statue of Liberty"
                    },
                    "address": {
                        "country": "United States Of America",
                        "freeformAddress": "New York, NY 10004"
                    }
                }
            ]
        },
        {
            "statusCode": 400,
            "message": "Bad Request"
        }
    ]
}


Data Retention Period

Please, be aware that batch results are available for download for 14 days, after which the request for results download will return 400 Bad Request response.

Post Search Inside Geometry

Applies to: S0 and S1 pricing tiers.

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.

To send the geometry you will use a POST request where the request body will contain the geometry object represented as a GeoJSON type and the Content-Type header will be set to application/json. 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. Please see the Examples section below for a sample Polygon representation.

.