Bing Maps Location Recognition API and Autosuggest API Previews Released
We are excited to announce the private preview release of two new Bing Maps APIs – Bing Maps Location Recognition API and Bing Maps Autosuggest API. Bing Maps Location Recognition API and the Bing Maps Autosuggest API will be generally available this summer.
Bing Maps Location Recognition Preview
By fully recognizing their user locations, apps & services can build the next gen experiences and analytics. Developers and analysts can use the Bing Maps Location Recognition API to build rich experiences like store specific notifications or coupons, visit tracking and identify new customer segments based on the types of location users visit.
Given a location (latitude, longitude) the Bing Maps Location Recognition API returns a list of entities situated at the location. Note that search by query is not supported. The different components of the API response provide a comprehensive description of the location. The API response consists of:
- Business entities situated at the location. A wide variety of entity types are supported (e.g. restaurants, hotels, parks, gym, shopping malls and more).
- Natural entities at the location (e.g. beaches, island, lakes and 9 other types).
- Reverse geocoded address of the input location, with neighborhood and street intersection information where available.
- Type of property (e.g. residential, commercial) situated at the location.
Supported business types/ categories
|
Arts & entertainment |
Automotive |
Banking & finance |
Beauty & spa |
|
Business-to-business |
Education |
Food & drink |
Government |
|
Healthcare |
News & media |
Professional services |
Real estate |
|
Religion |
Retail |
Sports & recreation |
Travel |
Note: granular categories are available under these top-level categories (e.g. different cuisines are available under ‘restaurants’ which itself is under ‘food & drink’).
Supported natural entity types
|
Bay |
Beach |
Canal |
Forest |
|
Island |
Lake |
Mountain |
Plateau |
|
Reserve |
River |
Sea |
Valley |
Example scenario: Trip labelling in MileIQ
Leading mileage tracking app MileIQ is using Location Recognition API to make it easy for users to label the start/ end of their trips. Location Recognition API is providing names of locations visited by a user in their trip, using these suggestions MileIQ users can easily label their trips.
Example scenario: Location sharing in Swiftkey
Popular keyboard app Swiftkey is using the Location Recognition API to power their new location sharing feature. For users given location, Location Recognition API is providing the reverse geocoded address that users can share with their friends and family.
Getting started
The table below describes the query parameters the Location Recognition API would support and fields included in a typical response (note, these are subject to change once we transition from private preview to general availability).
Query parameters
|
Parameter |
Description |
Values |
|
point |
Required. The coordinates of the location that you want to reverse geocode. A point is specified by a latitude and a longitude. For more information, see the definition of Point in Location and Area Types. |
A point on the Earth specified by a latitude and longitude. For more information, see the definition of Point in Location and Area Types. Example: 47.64054, -122.12934 |
|
radius |
Optional. Search radius in KM. Search is performed within a circle of specified radius and centered on the given location. |
Default search radius is 0.25KM, maximum supported radius is 2KM |
|
distanceUnit |
Optional. Unit for the radius parameter, use one of the following values • kilometer or km • miles or mi |
Default value is km |
|
top |
Optional. Number of results to be returned. If more results are found in the specified search radius, the number of results is limited by the value of top parameter. |
Maximum supported value is 20 |
|
key |
Required. Valid Bing Maps key |
Response
|
Field |
Description |
|
Businesses and points of interest |
Up to 20 local businesses (e.g. restaurants, offices, transit etc.) and points of interest situated at the input location |
|
Natural points of interest |
Natural entities (e.g. beach, forest, lake etc.) situated at the input location |
|
Address |
Reverse geocoded address of the input location with neighborhood information where available |
Bing Maps Autosuggest Preview
Bing Maps Autosuggest is a service built by the Location Intelligence team at Bing Maps. Given a partial query, the service returns a list of suggested entities the user is most likely searching for. We return entities for: roads, addresses, places and businesses (Businesses are currently constrained to en-US). This service is currently in preview mode and will be available this summer.
Below are details regarding the expected parameters and output. Note that none of this will be finalized until we transition from preview to full launch. First, here’s the list of parameters expected to be part of the API signature:
Query parameters
|
query (alias: q) |
Required |
Query prefix that user has typed in e.g. “1 Micro” (potentially the prefix for “1 Microsoft Way, Redmond, WA 98052”) |
|
userLocation (alias: ul) |
Required (unless either ucmv or ucrv are specified) |
Location user is searching from and confidence radius of accuracy in meters of that point, e.g.: 48.604311,-122.981998,5000. This is the location of the downstream user, not the server the service is being called from. UserLocation becomes a secondary signal if either UserCircularMapView or UserMapView is passed in as well. |
|
userCircularMapView (alias: ucmv) |
Optional |
The geographic area to search for local places. The area is expressed as a circle as (lat,long,radius), where lat and long are the coordinates of the circle’s center e.g. 48.604311,-122.981998,5000. UserCircularMapView is mutually exclusive from UserMapView. Both UserCircularMapView and UserMapView are used as ranking features. They are not physical constraints on the suggestions. |
|
userMapView (alias: urmv) |
Optional |
Allows the returned suggestions to be bounded to a bounding box. The box is defined by 4 values: South Latitude, West Latitude, North Latitude, East LongitudeNW corner latitude, NW corner longitude, SE corner latitude, SE corner longitude. E.g. 29.8171041, -122.981995, 48.604311, -95.5413725. UserMapView is mutually exclusive from UserCircularMapView. Both UserCircularMapView and UserMapView are used as ranking features. They are not physical constraints on the suggestions. |
|
maxRes (alias: mr) |
Optional |
Maximum number of suggestions to return. Default is 7, Maximum is 10. Minimum is 1. |
|
types |
Optional |
Specify types of locations to return. The types are: Place, Address, Business. E.g.: Place, Address. By default all 3 are on. |
|
culture (alias: c) |
Optional |
The language to use for user interface strings. E.g. en-GB. By default this is set to en-US |
|
userRegion (alias: m) |
Optional |
The market the user is in as denoted by its 2-letter country code abbreviation. E.g. DE for Germany. The default is US. |
|
countryFilter (alias: cf) |
Optional |
Constrain suggestions to only those in a single country via a 2-character ISO country code. E.g. “DE”. The default is none. |
Below are fields you can expect in the output. Responses include some subset of what’s below depending on the entity type.
Output fields
|
ResourceSets |
Container of returned structured suggestions |
|
Resources |
A structured entity suggestion |
|
Error |
Defines an error that occurred |
|
__type |
The type of suggested result, e.g. Place |
|
houseNumber |
Just the house number of a street address. e.g. 2100 This may be blank for road entities. |
|
streetName |
Just the street name of a street address. E.g. Westlake Ave N. |
|
addressLine |
The street address e.g. 2100 Westlake Ave N. |
|
locality |
The city where the street address is located e.g. Seattle |
|
adminDistrict2 |
The name of the county where the street address is located e.g. King. |
|
adminDistrict |
The state or province code when the street address is located. This could be the two-letter code (e.g. WA) or the full name (e.g. Washington) |
|
countryRegion |
The name of the country/region where the street address is located e.g. United States |
|
countryRegionIso2 |
The ISO code for the country/region where the street address is located e.g. US |
|
Neighborhood |
The neighborhood where the street address is located e.g. Westlake |
|
PostalCode |
The zip code or postal code where the street address is located e.g. 98052 |
|
formattedAddress |
The complete address of the location. e.g. 7625 170th Ave NE, Redmond, WA 98052 |
|
entityType |
A list of hints that indicate the type of entity. The list may contain a single hint such as PopulatedPlace or a list of hints such as Place, LocalBusiness, Restaurant. Each successive hint in the array narrows the entity's type. |
|
name |
Name of a place or business e.g. Washington, Starbucks. All POI have names; however, places that are typically found in the geochain |
Finally, check out an example of how one could visualize these suggestions quite quickly. In the example below, there were originally 5 POI markers for the suggestions, and we used an eraser tool to hide 2 of them.
Enroll in our preview program
Contact maplic@microsoft.com for enrollment in the private preview programs for both Bing Maps Location Recognition API and Bing Maps Autosuggest API.
We hope you enjoy exploring our new APIs as much as we enjoyed building them. As always, we welcome your feedback. Let us know what you think about the APIs and what you would like to see in future releases by reaching out to the team at Bing Maps Forum.
– Bing Maps Team
Source: Bing Blog Feed