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.

MileIQ Trip Labelling

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.

Swiftkey Location Sharing

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.

Bing Maps Autosuggest Visualizer

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

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.