Autosuggest

Bing
 

Given a request with a user’s location and a partial query (called a query prefix), the Bing Maps Autosuggest API returns a list of suggested entities which the user is most likely searching for. These entities are ranked from most to least likely. Requests can be called using user locations (as the geocoordinates of the user, including a radius representing your confidence in the accuracy of the user’s location), and/or as a geographic region (either a circle or rectangle, but not both).

System_CAPS_ICON_note.jpg Note

Geographic regions defined using map view parameters only influence suggested entity rankings.

Suggested entities are not guaranteed to lie inside geographic regions.

There are three possible kinds of entities: Addresses/Roads, Places, and Businesses. Requests can be specified to return any combination of these entities.

Presently, Business entities are only available in the en-US culture.

http://dev.virtualearth.net/REST/v1/Autosuggest?query=<user_prefix>&userLocation=<lat,long,confidence_radius>&userCircularMapView=<lat,long,radius>&userMapView=<nw_lat,nw_long,se_lat,se_long>&maxResults=<max_results>&includeEntityTypes=<Place,Address,Business>&culture=<culture_code>&userRegion=<country_code>&countryFilter=<country_code_or_none>&key=<BingMapKey>

System_CAPS_ICON_note.jpg Note

Only the query parameter is unconditionally required. The userLocation parameter is required if neither of the optional parameters userCircularMapView nor userMapView are provided.

The parameters userCircularMapView and userMapView are mutually exclusive.

ParametersAliasDescription
queryqRequired. The user's query prefix.

Example: "1 Micro" or "El Gaucho".
userLocationulRequired if neither userCircularMapView nor userMapView are provided. A comma separated list of the user’s location (latitude, longitude) and radius, in meters, representing the confidence in the accuracy of the user’s location.

Example: 48.604311,-122.981998,5000

Note: userLocation becomes a secondary signal if either UserCircularMapView or UserMapView is provided.
userCircularMapViewucmvOptional. A circular geographic region specified by a comma separated list of the latitude and longitude of the center of the circle, and the radius of the circle, in meters.

Example: 48.604311,-122.981998,5000

Note. Mutually exclusive from userMapView.
userMapViewumvOptional. A rectangular region (a bounding box) specified by a comma separated list of the latitudes and longitudes of two corners of the rectangle:

- Latitude of the Northwest corner
- Longitude of the Northwest corner
- Latitude of the Southeast corner
- Longitude of the Southeast corner

Example: 29.8171041,-122.981995,48.604311,-95.5413725

Note: Mutually exclusive from userCircularMapView.
maxResultsmaxResOptional. The maximum number of returned suggestions and can be any integer in [1, 10].

Default: 7.
includeEntityTypesinclenttypeOptional. A comma separated list of returned entity types. The possible values are:
 
- Address
- Place
- Business

Note: These types are mutually inclusive. Place represents points of interest, like natural landmarks.

Default: Address,Place,Business
culturecOptional. The language of query prefixes.

Example: en-GB.

Default: en-US.
userRegionurOptional. The user’s market denoted by 2-letter country code abbreviations.

Example: DE.

Default: US.
countryFiltercfOptional. Used to constrain entity suggestions to a single country denoted by a 2-letter country code abbreviation.

Example: DE.

Default: none.
outputoOptional. Format of the response:

- JSON
- XML

Default: JSON.

Response formats are available in both JSON and XML.

As shown in the table below, the response format of the three resource entities -- Business, Place, and Address -- vary.

Resource Type FieldResource Fields
__type: “Address”- houseNumber
- streetName
- addressLine
- locality
- adminDistrict
- adminDistrict2
- countryRegion
- countryRegionIso2
- neighborhood
- postalCode
- formattedAddress
__type: “Place”- entityType
- name
- addressLine
- locality
- adminDistrict
- adminDistrict2
- countryRegion
- countryRegionIso2
- neighborhood
- postalCode
- formattedAddress 
__type: “LocalBusiness”- entityType
- name
- addressLine
- locality
- adminDistrict
- adminDistrict2
- countryRegion
- countryRegionIso2
- neighborhood
- postalCode
- formattedAddress 
Response FieldsDescription
ResourceSetsContainer of returned resources.
ResourcesStructured entity suggestion.
ErrorIf an error occurred, defines the errors.
__typeThe type of resource.
houseNumberThe house number for a street address. e.g. 2100. May be blank for road entities. 
streetNameThe street name of a street address, e.g. Westlake Ave N.
addressLineThe street address of a resource, e.g. 2100 Westlake Ave N.
localityThe city in which a resource is located, e.g. Seattle.
adminDistrict2The name of the county in which a resource is located, e.g. King.
adminDistrictThe state or province code for a street address. Usually a two-letter code, e.g. WA, or the full name, e.g. Washington.
countryRegionThe name of the country or region in which the street address is located, e.g. United States. 
countryRegionIso2The two-letter ISO code for the country or region in which the street address is located, e.g. US.
NeighborhoodThe neighborhood in which the street address is located, e.g. Westlake.
PostalCodeThe zip or postal code for the the street address , e.g. 98052.
formattedAddressThe complete address of the resource, e.g. 7625 170th Ave NE, Redmond, WA 98052.
entityTypeA list of hints which indicate the resource type.
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 list narrows down the entity's type.
nameName of a place or business, e.g. Washington, or Starbucks.
All places of interest have names, but the name may be located in the address fields.

Example: Searching for a business

Consider the case of a user typing in an HTML form to search for a place to eat, and that we are sure the user’s location is in the Ballard neighborhood of Seattle, e.g. at the location 47.668697,-122.376373.

As the user starts typing, we can use a partial query like “El bur” as a query prefix, and send the following URL request:

http://dev.virtualearth.net/REST/v1/Autosuggest?query=El%20bur&userLocation=47.668697,-122.376373,5&includeEntityTypes=Business&key=<BingMapsKey>

And the JSON response:

{
    "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": "Autosuggest:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
                    "value": [
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Kirkland",
                                "adminDistrict": "WA",
                                "countryRegionIso2": "US",
                                "postalCode": "98034",
                                "addressLine": "12412 116th Ave NE",
                                "formattedAddress": "12412 116th Ave NE, Kirkland, WA 98034"
                            },
                            "name": "El Burrito Mojado"
                        },
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Kirkland",
                                "adminDistrict": "WA",
                                "countryRegionIso2": "US",
                                "postalCode": "98032",
                                "addressLine": "111 116th Ave NE",
                                "formattedAddress": "111 116th Ave NE, Kirkland, WA 98032"
                            },
                            "name": "El Burrito Mojado"
                        },
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Portland",
                                "adminDistrict": "OR",
                                "countryRegionIso2": "US",
                                "postalCode": "97213",
                                "addressLine": "6728 NE Sandy Blvd",
                                "formattedAddress": "6728 NE Sandy Blvd, Portland, OR 97213"
                            },
                            "name": "El Burrito Azteca"
                        },
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Portland",
                                "adminDistrict": "OR",
                                "countryRegionIso2": "US",
                                "postalCode": "97217",
                                "addressLine": "1942 N Rosa Parks Way",
                                "formattedAddress": "1942 N Rosa Parks Way, Portland, OR 97217"
                            },
                            "name": "El Burrito Azteca"
                        },
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Portland",
                                "adminDistrict": "OR",
                                "countryRegionIso2": "US",
                                "postalCode": "97220",
                                "addressLine": "3126 NE 82nd Ave",
                                "formattedAddress": "3126 NE 82nd Ave, Portland, OR 97220"
                            },
                            "name": "El Burrito Loco"
                        },
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Welches",
                                "adminDistrict": "OR",
                                "countryRegionIso2": "US",
                                "postalCode": "97067",
                                "addressLine": "67211 E Highway 26",
                                "formattedAddress": "67211 E Highway 26, Welches, OR 97067"
                            },
                            "name": "El Burro Loco"
                        },
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Portland",
                                "adminDistrict": "OR",
                                "countryRegionIso2": "US",
                                "postalCode": "97203",
                                "addressLine": "7316 N Lombard St",
                                "formattedAddress": "7316 N Lombard St, Portland, OR 97203"
                            },
                            "name": "El Burrito Mojado"
                        }
                    ]
                }
            ]
        }
    ],
    "statusCode": 200,
    "statusDescription": "OK",
    "traceId": "b9a0e48d52164cdfa239f4152a7940e4|CO36161B45|7.7.0.0"
}

There are seven suggested entities returned by the Autosuggest API. The first two entities are businesses near Seattle (in Kirkland). There are also four businesses in Portland, Oregon, and another business in Welches, Oregon.

Example: Searching for Addresses and Places of Interest

Using the same query prefix as above, suppose you change the includeEntityTypes to exclude businesses and only search for suggested addresses and points of interest.

Here is the URL request:

http://dev.virtualearth.net/REST/v1/Autosuggest?query=El%20bur&userLocation=47.668697,-122.376373,5&includeEntityTypes=Address,Place&key=<BingMapsKey>

And the JSON response:

{
    "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": "Autosuggest:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
                    "value": [
                        {
                            "__type": "Place",
                            "address": {
                                "countryRegion": "Mexico",
                                "locality": "El Burrión",
                                "adminDistrict": "Sinaloa",
                                "adminDistrict2": "Guasave Municipality",
                                "countryRegionIso2": "MX",
                                "formattedAddress": "El Burrión, Sinaloa"
                            }
                        },
                        {
                            "__type": "Place",
                            "address": {
                                "countryRegion": "Mexico",
                                "locality": "El Burro",
                                "adminDistrict": "Chihuahua",
                                "countryRegionIso2": "MX",
                                "formattedAddress": "El Burro, Chihuahua"
                            }
                        },
                        {
                            "__type": "Place",
                            "address": {
                                "countryRegion": "Mexico",
                                "locality": "El Burócrata",
                                "adminDistrict": "Durango",
                                "adminDistrict2": "Durango",
                                "countryRegionIso2": "MX",
                                "formattedAddress": "El Burócrata, Durango"
                            }
                        }
                    ]
                }
            ]
        }
    ],
    "statusCode": 200,
    "statusDescription": "OK",
    "traceId": "2132c961bd0e455fa21402c38b5e3dd6|CO389F482F|7.7.0.0"
}

Instead of returning a list of suggested businesses similar to the query prefix "El Bur", the Autosuggest API returns of list of suggested places and addresses. In this case, a list of three suggested addresses in Mexico.

You can restrict suggested entities to a single country by specifying the countryFilter parameter. For example, we could set countryFilter to US.

Here is the URL request:

http://dev.virtualearth.net/REST/v1/Autosuggest?query=El%20bur&userLocation=47.668697,-122.376373,5&includeEntityTypes=Address,Place&countryFilter=US&key=<BingMapKey>

However, in this case, the JSON response returns an empty list of suggested entities!

But that’s alright. The Autosuggest API is meant to be called multiple times, with the same user location information, but with different query prefixes.

For example, suppose the same user changes the partial query from "El Bur" to "Buri" -- perhaps because they are looking for addresses with the keyword "Burien".

Here is the new URL request:

http://dev.virtualearth.net/REST/v1/Autosuggest?query=Buri&userLocation=47.668697,-122.376373,5&includeEntityTypes=Address,Place&countryFilter=US&key=<BingMapKey>

And the JSON response:

{
    "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": "Autosuggest:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
                    "value": [
                        {
                            "__type": "Place",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Burien",
                                "adminDistrict": "Washington",
                                "adminDistrict2": "King County",
                                "countryRegionIso2": "US",
                                "formattedAddress": "Burien, Washington"
                            }
                        }, {   
                            "__type": "Place",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Burien",
                                "adminDistrict": "Washington",
                                "adminDistrict2": "King County",
                                "countryRegionIso2": "US",
                                "formattedAddress": "Burien, Washington"
                            },
                            "name": "Burien Community Center Park"
                        },
                        {
                            "__type": "Address",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Seattle",
                                "adminDistrict": "Washington",
                                "adminDistrict2": "King County",
                                "countryRegionIso2": "US",
                                "houseNumber": "",
                                "addressLine": "Burien Fwy",
                                "streetName": "Burien Fwy",
                                "formattedAddress": "Burien Fwy, Seattle, Washington"
                            }
                        },
                        {
                            "__type": "Address",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Burien",
                                "adminDistrict": "Washington",
                                "adminDistrict2": "King County",
                                "countryRegionIso2": "US",
                                "houseNumber": "",
                                "addressLine": "Burien Fwy",
                                "streetName": "Burien Fwy",
                                "formattedAddress": "Burien Fwy, Burien, Washington"
                            }
                        },
                        {
                            "__type": "Place",
                            "address": {
                                "countryRegion": "United States",
                                "adminDistrict": "California",
                                "adminDistrict2": "San Mateo County",
                                "countryRegionIso2": "US",
                                "formattedAddress": "California"
                            },
                            "name": "Buri Buri Park"
                        },
                        {
                            "__type": "Place",
                            "address": {
                                "countryRegion": "United States",
                                "adminDistrict": "Nevada",
                                "countryRegionIso2": "US",
                                "formattedAddress": "Nevada"
                            },
                            "name": "Buried Hills"
                        },
                        {
                            "__type": "Place",
                            "address": {
                                "countryRegion": "United States",
                                "adminDistrict": "California",
                                "adminDistrict2": "Riverside County",
                                "countryRegionIso2": "US",
                                "formattedAddress": "California"
                            },
                            "name": "Buried Mountain"
                        }
                    ]
                }
            ]
        }
    ],
    "statusCode": 200,
    "statusDescription": "OK",
    "traceId": "69d954d4ecfa45209bfb5574ac48e35f|CO320968BC|7.7.0.0"
}

The same user can now be shown a new list of suggested entities. This time a list of addresses and places of interest in Washington, Nevada, and California.

Example: Searching by Geographical Region

Geographical regions have many applications. Like using a circular region to rank higher those entities that are in walking range, or drawing a bounding box to cover a map currently being shown on the user’s mobile screen.

Consider this URL request:

http://dev.virtualearth.net/REST/v1/Autosuggest?query=fish&userLocation=47.668697,-122.376373,5&userCircularMapView=47.668697,-122.376373,100&includeEntityTypes=Business&key=<BingMapKey>

Here is the JSON response:

{
    "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": "Autosuggest:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
                    "value": [
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Seattle",
                                "adminDistrict": "WA",
                                "countryRegionIso2": "US",
                                "postalCode": "98119",
                                "addressLine": "3919 18th Ave W",
                                "formattedAddress": "3919 18th Ave W, Seattle, WA 98119"
                            },
                            "name": "Fishermen's Terminal"
                        },
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Seattle",
                                "adminDistrict": "WA",
                                "countryRegionIso2": "US",
                                "postalCode": "98119",
                                "addressLine": "1511 W Thurman St",
                                "formattedAddress": "1511 W Thurman St, Seattle, WA 98119"
                            },
                            "name": "Fishing Vessel Owners Marine Ways"
                        },
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Seattle",
                                "adminDistrict": "WA",
                                "countryRegionIso2": "US",
                                "postalCode": "98103",
                                "addressLine": "1900 N Northlake Way",
                                "formattedAddress": "1900 N Northlake Way, Seattle, WA 98103"
                            },
                            "name": "Fisheries Supply"
                        },
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Seattle",
                                "adminDistrict": "WA",
                                "countryRegionIso2": "US",
                                "postalCode": "98101",
                                "addressLine": "1301 Alaskan Way",
                                "formattedAddress": "1301 Alaskan Way, Seattle, WA 98101"
                            },
                            "name": "Fisherman's Restaurant"
                        },
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Seattle",
                                "adminDistrict": "WA",
                                "countryRegionIso2": "US",
                                "postalCode": "98109",
                                "addressLine": "298 2nd Ave N",
                                "formattedAddress": "298 2nd Ave N, Seattle, WA 98109"
                            },
                            "name": "Fisher Pavilion"
                        },
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Seattle",
                                "adminDistrict": "WA",
                                "countryRegionIso2": "US",
                                "postalCode": "98107",
                                "addressLine": "5200 Ballard Ave NW",
                                "formattedAddress": "5200 Ballard Ave NW, Seattle, WA 98107"
                            },
                            "name": "Macleod's Scottish Pub"
                        },
                        {
                            "__type": "LocalBusiness",
                            "address": {
                                "countryRegion": "United States",
                                "locality": "Seattle",
                                "adminDistrict": "WA",
                                "countryRegionIso2": "US",
                                "postalCode": "98109",
                                "addressLine": "305 Harrison St",
                                "formattedAddress": "305 Harrison St, Seattle, WA 98109"
                            },
                            "name": "Seattle Center"
                        }
                    ]
                }
            ]
        }
    ],
    "statusCode": 200,
    "statusDescription": "OK",
    "traceId": "a682402a1b6e426a9f177c0dc67f7b06|CO3230EE0A|7.7.0.0"
}

In this response, several suggested businesses are returned. Notice that the list is not ordered by increasing distance from the user. Indeed, except for Macleod’s Scottish Pub, none of the suggested entities are near downtown Ballard. In fact, all the business entities are outside the circular geographical region. Geography regions influence the list of suggested entities, but entities outside of the specified geographic regions may still be in the returned list of suggested entities.

System_CAPS_ICON_note.jpg Note

Different kinds of businesses are also returned. In the above response, for example, restaurants that serve fish are in the same list as fishing supply stores.

This diversity of business entities is a feature of the Autosuggest API.

Example: Providing Geographic Regions

This section briefly shows how to provide geographic parameters when sending a URL request to the Autosuggest API.

Circular Geographic Region

Example:

userCircularMapView=47.666673,-122.382242,100

AutoSuggestCircleSmall

Bounding Box Geographic Region

Example:

userMapView=47.669424,-122.386053,47.664083,-122.378448

AutoSuggestBoundingBoxSmall

System_CAPS_ICON_note.jpg Note

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

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

  • 200

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

  • 400
Show: