Location Recognition

Article
05/21/2024

Note

Bing Maps Location Recognition API retirement

Bing Maps Location Recognition API is deprecated and will be retired. Free (Basic) account customers can continue to use Bing Maps Location Recognition API until June 30th, 2025. Enterprise account customers can continue to use Bing Maps Location Recognition API until June 30th, 2028. To avoid service disruptions, all implementations using Bing Maps Location Recognition API will need to be updated to use Azure Maps by the retirement date that applies to your Bing Maps for Enterprise account type.

Azure Maps is Microsoft's next-generation maps and geospatial services for developers. Azure Maps has many of the same features as Bing Maps for Enterprise, and more. To get started with Azure Maps, create a free Azure subscription and an Azure Maps account. For more information about azure Maps, see Azure Maps Documentation. For migration guidance, see Bing Maps Migration Overview.

Given a pair of location coordinates (latitude, longitude), the Location Recognition API returns a list of entities ranked by their proximity to that location. The URL response contains three components: local business entities near that location (e.g. restaurants, hotels, office buildings, transit stations, etc.), natural points of interest near that location (e.g. beaches, valleys, etc.), and a reverse geocoded address of that location. See Location Recognition Entity Types for a list of supported entity types. You can specify the type of entities you want to receive by setting the includeEntityTypes parameter in the URL.

Note

This template supports both HTTP and HTTPS protocols
Search by query is not supported
Locations in Canada, Germany, Italy, Spain and USA are supported, other countries/regions will be added soon

URL Template

Get a list of entities at a specific location

https://dev.virtualearth.net/REST/v1/LocationRecog/{point}?radius={search_radius}&top={number_of_results}&datetime={visit_date_time}&distanceunit={dist_unit}&verboseplacenames={true_or_false}&includeEntityTypes={list_of_entity_types}&key={BingMapsKey}

API Parameters

Parameters	Alias	Description	Values
`point`		Required. The coordinates of the location for which you want the entities situated at that location. A point is specified by a latitude and a longitude. See the definition of point in Location and Area Types.	Use the following value ranges: Latitude (degrees): `[-90, +90]` Longitude (degrees): `[-180, +180]` Example: `47.610679194331169,-122.10788659751415`
`radius`	`r`	Optional. Search radius in kilometers (KM). Search is performed within a circle with the specified radius and centered at the location point. Only those entities that fall within this search circle are returned.	Default search radius is 0.25 KM. The maximum supported radius is 2 KM.
`top`		Optional. The maximum number of entities returned.	Default value is 10. The maximum value is 20.
`dateTime`		Optional. Date and time at which the location is visited, in UTC format. When this parameter is specified, entities closed at that day and/or time are ranked lower than entities which are open.	Example: `2018-05-09 13:34:42Z`
`distanceUnit`		Optional. Unit for the radius parameter.	Use one of the following values: - `kilometer`, or `km` - `mile`, or `mi` Default value is `km`.
`verboseplacenames`		Optional. Either `true` or `false`. - If `false`: "admin1" & country/region names will be in their official form (e.g.: “WA” for Washington state in USA and full name, e.g. "Occitanie" in France). -If `true`: "admin1" names will be in expanded form (e.g. Washington), and "countryRegion" field with full name is added to address.	Default value is `false`.
`includeEntityTypes`		Optional. Specifies the entity types returned in the response. Only the specified types will be returned. If no entity types are found at the location point, then no location information is returned in the response. See Location Recognition Entity Types for a description of the values.	A comma separated list of entity types selected from the following options: - `businessAndPOI` - `naturalPOI` - `address` Default value is `businessAndPOI`.
`type`		Optional. Specifies which business and POI category types to limit the entities returned by the Location Recognition API to if using the includeEntityTypes parameter value of `businessAndPOI` (which is the default value).	A comma-separated list of string type identifiers. See the list of available Type IDs
`output`	`o`	Optional. Output format for the response.	The following values are supported: - `JSON` - `XML` Default value is `JSON`.

Include Entity Types

Entity Type	Description	Example
`businessAndPOI`	Local businesses and points of interest.	Restaurants, hotels, hospitals, airports, train & bus stations Office buildings Municipal & national parks Landmarks or popular buildings
`naturalPOI`	Points of interest, including natural entities.	Lakes, beaches, mountains, valleys, and forests
`address`	Reverse geocoded address of the input location. For a description of the address fields, refer to Location and Area Types.	1 Microsoft Way, Redmond, WA 98052, US

For more information about the location entity types, see Location Recognition Entity Types.

Response

One or more entities are returned in the response when you make a request using this URL.

Field Name	Description
`businessesAtLocation`	List of businessAddress & businessInfo elements representing the businesses or named venues found within the specified search radius.
`naturalPOIAtLocation`	Natural entities or points of interest. For a complete list of supported natural entity types see Location Recognition Entity Types.
`addressOfLocation`	Reverse geocoded address of the input location.

For more information about the location entity types, see Location Recognition Entity Types. For information about the common response syntax for the Bing Maps REST Services, see Common Response Description.

Examples

Find all entities at point on Earth in XML.

This example gets entities situated at a specified location and requests the response in xml format.

http://dev.virtualearth.net/REST/v1/locationrecog/47.640068,-122.129860?key={BingMapsKey}&output=xml

Here is the XML Response (truncated for brevity):

<?xml version="1.0" encoding="ISO-8859-1"?>
<Response xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Copyright>Copyright © 2018 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.</Copyright>
  <BrandLogoUri>http://dev.virtualearth.net/Branding/logo_powered_by.png</BrandLogoUri>
    <StatusCode>200</StatusCode>
    <StatusDescription>OK</StatusDescription>
    <AuthenticationResultCode>ValidCredentials</AuthenticationResultCode>
    <TraceId>7f3146adab974e9b95a665b7099eb692|CO30276242|7.7.0.0</TraceId>
    <ResourceSets>
      <ResourceSet>
        <EstimatedTotal>1</EstimatedTotal>
        <Resources>
          <Resource xsi:type="LocationRecog">
            <IsPrivateResidence>False</IsPrivateResidence>
            <BusinessesAtLocation>
              <BusinessLocationEntity>
                <BusinessAddress>
                  <Latitude>47.640155</Latitude>
                  <Longitude>-122.129788</Longitude>
                  <AddressLine>1 Microsoft Way Bldg 98</AddressLine>
                  <Locality>Redmond</Locality>
                  <AdminDivision>WA</AdminDivision>
                  <CountryIso2>US</CountryIso2>
                  <PostalCode>98052</PostalCode>
                  <FormattedAddress>1 Microsoft Way Bldg 98, Redmond, WA 98052, US</FormattedAddress>
                </BusinessAddress>
                <BusinessInfo>
                  <Id>873x131243969</Id>
                  <EntityName>Eastside Ski & Sport</EntityName>
                  <Url>http://www.eastsideskiandsport.com/</Url>
                  <Phone>(425) 885-3000</Phone>
                  <TypeId>90628</TypeId>
                  <OtherTypeIds>
                    <int>91518</int>
                    <int>91517</int>
                    <int>90826</int>
                  </OtherTypeIds>
                  <Types>Retail</Types>
                  <OtherTypes>
                    <string>Outdoor Recreational Equipment Stores</string>
                    <string>Bicycle Shops</string>
                    <string>Sports & Outdoors</string>
                  </OtherTypes>
                </BusinessInfo>
              </BusinessLocationEntity>
              <BusinessLocationEntity>
                <BusinessAddress>
                  <Latitude>47.640012</Latitude>
                  <Longitude>-122.129756</Longitude>
                  <AddressLine>1 Microsoft Way</AddressLine>
                  <Locality>Redmond</Locality>
                  <AdminDivision>WA</AdminDivision>
                  <CountryIso2>US</CountryIso2>
                  <PostalCode>98052</PostalCode>
                  <FormattedAddress>1 Microsoft Way, Redmond, WA 98052, US</FormattedAddress>
               </BusinessAddress>
               <BusinessInfo>
                 <Id>873x8648196069879702717</Id>
                 <EntityName>Microsoft Alumni Network</EntityName>
                 <Url>http://microsoftalumni.com/</Url>
                 <Phone>(425) 885-3500</Phone>
                 <TypeId>91254</TypeId>
                 <OtherTypeIds>
                   <int>90298</int>
                 </OtherTypeIds>
                 <Types>Charitable Organizations</Types>
                 <OtherTypes>
                   <string>Government & Community</string>
                 </OtherTypes>
               </BusinessInfo>
             </BusinessLocationEntity> 
             
             <!-- * * * -->

           </BusinessesAtLocation>
           <AddressOfLocation>
             <AddressInfo>
             <Latitude>47.640068</Latitude>
             <Longitude>-122.12986</Longitude>
             <AddressLine>1 Microsoft Way</AddressLine>
             <Locality>Redmond</Locality>
             <Neighborhood>Overlake</Neighborhood>
             <AdminDivision>WA</AdminDivision>
             <CountryIso2>US</CountryIso2>
             <PostalCode>98052</PostalCode>
             <FormattedAddress>1 Microsoft Way, Redmond, WA 98052, US</FormattedAddress>
           </AddressInfo>
         </AddressOfLocation>
         <VendorIds>
           <int>3</int>
           <int>208</int>
           <int>224</int>
           <int>225</int>
         </VendorIds>
       </Resource>
     </Resources>
   </ResourceSet>
 </ResourceSets>
</Response>

Find natural entities situated at a specified point on Earth.

This example uses the includeEntityTypes parameter to search for natural entities at a point in JSON format.

http://dev.virtualearth.net/REST/v1/locationrecog/47.640068,-122.129860?key={BingMapsKey}&output=json

HTTP response in JSON:

{
    "authenticationResultCode": "ValidCredentials",
    "brandLogoUri": "http://dev.virtualearth.net/Branding/logo_powered_by.png",
    "copyright": "Copyright © 2018 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.",
    "resourceSets": [
      {
        "estimatedTotal": 1,
        "resources": [
          {
            "__type": "LocationRecog:http://schemas.microsoft.com/search/local/ws/rest/v1",
            "naturalPOIAtLocation": [
              {
                "entityName": "Alki Beach Park",
                "latitude": 47.595383,
                "longitude": -122.38659,
                "type": "Beach"
              }
            ]
          }
        ]
      }
    ],
    "statusCode": 200,
    "statusDescription": "OK",
    "traceId": "288b508676fb497db1b5cb6525aa0b10|CO30275836|7.7.0.0"
  }

Find the address for a point on Earth.

This URL request gets the address for a point in Downtown Seattle in the JSON format.

http://dev.virtualearth.net/REST/v1/locationrecog/47.609722,-122.333056?key={BingMapsKey}&includeEntityTypes=address&output=json

HTTP Request in JSON:

{
    "authenticationResultCode": "ValidCredentials",
    "brandLogoUri": "http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",
    "copyright": "Copyright c 2018 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.",
    "resourceSets": [
        {
            "estimatedTotal": 1,
            "resources": [
                {
                    "__type": "LocationRecog:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
                    "isPrivateResidence": "True",
                    "businessesAtLocation": [],
                    "addressOfLocation": [
                        {
                            "latitude": 47.60975,
                            "longitude": -122.33287,
                            "addressLine": "1314 6th Ave",
                            "locality": "Seattle",
                            "neighborhood": "Central Business District",
                            "adminDivision": "WA",
                            "countryIso2": "US",
                            "postalCode": "98101",
                            "formattedAddress": "1314 6th Ave, Seattle, WA 98101, US"
                        }
                    ]
                }
            ]
        }
    ],
    "statusCode": 200,
    "statusDescription": "OK",
    "traceId": "6503238c004d4d9384a77d6bd61de26d|CO3035AD45|7.7.0.0"
}

This example gets entities for a specified latitude and longitude and requests the results in XML format.

http://dev.virtualearth.net/REST/v1/LocationRecog/47.640068,-122.129860?key={BingMapsKey}&output=xml

We can also make the same request, but this time searching for business entities within half a mile of the point:

http://dev.virtualearth.net/REST/v1/locationrecog/47.609722,-122.333056?key={BingMapsKey}&r=.5&distanceUnit=mi&includeEntityTypes=address&output=json

This example sets the type parameter, which will limit the returned business entities to the specified POI category type(s), in this case hotels and motels.

http://dev.virtualearth.net/REST/v1/locationrecog/47.609722,-122.333056?key={BingMapsKey}&r=.5&distanceUnit=mi&type=HotelsAndMotels&output=json

HTTP Status Codes

Note

For more details about these HTTP status codes, see Status Codes and Error Handling.

When the request is successful, the following HTTP status code is returned:

When the request is not successful, the response returns one of the following errors:

Partager via

Location Recognition

URL Template

Get a list of entities at a specific location

API Parameters

Include Entity Types

Response

Examples

Find all entities at point on Earth in XML.

Find natural entities situated at a specified point on Earth.

Find the address for a point on Earth.

HTTP Status Codes

Ressources supplémentaires