-->
A complete list of languages supported by the Bing Maps V7 AJAX control can be found in the Returning a Localized Map documentation. Here is an example of Paris in Bing Maps with the mkt parameter set to “fr-FR”. After: Using Bing Maps REST Services In many some cases you may want to use the Bing Maps REST. On the Bing Maps forums I often come across developers who have difficulty accessing the Bing Maps REST services using different JavaScript frameworks such as jQuery and AngularJS. One common point of confusion is that passing in a REST service request URL into the address bar of a browser works, but passing that same URL into an AJAX method in JavaScript doesn’t. AJAX allows web pages to.
Use the following URL templates to get latitude and longitude coordinates for a location by specifying values such as a locality, postal code, and street address.
When you make a request by using one of the following URL templates, the response returns one or more Location resources that contain location information associated with the URL parameter values. The location information for each resource includes latitude and longitude coordinates, the type of location, and the geographical area that contains the location. For more information about the Location resource, see Location Data. You can also view the example URL and response values in the Examples section.
URL Templates
Note
These templates support both HTTP and HTTPS protocols.To use this API, you must have a Getting a Bing Maps Key.
Tip
Be sure to review the Bing Maps API Best Practices guide before using this service.
Get the latitude and longitude coordinates based on a set of address values for any country
A URL appends the location data to the URL path. In the URL below, address information is specified by using URL address parameters such as addressLine, adminDistrict. and postalCode. These parameters are appended to the URL path.
You can get information for a location in any country by setting one or more of the parameters in the following URL.
Get the latitude and longitude coordinates based on a set of address values for specific countries**
Note
You can substitute a hyphen (-) for any structured URL parameter when there is no value.
For countries that do not have a structured URL template, use the Unstructured URL described below or use the Find a Location by Query API which takes location well as encode other special characters information as a single query string.
For all location values, it is a best practice to encode the URI before making the request. Encoding replaces spaces with '%20' and replaces other special characters with similar encoded values. For more information, see encodeURI [JavaScript] and Uri.EscapeDataString [.NET].
A structured URL specifies the location data for the country as part of the URL path.
Canada
France
Germany
United Kingdom
United States
Important
About Special Characters
When you specify location information using one of the structured URLs, do not use values that contain special characters such as a period (.), a comma (,), a colon (:), or a plus sign (+). A hyphen is acceptable as a placeholder but should not be used as part of a parameter value in a structured URL. If the location information contains any special characters use the following structured URL template or the Find a Location by Query API.
For example, if you want to get latitude and longitude values for the address '100 Main St. Somewhere, WA 98001' that contains a period (.), use one of the following query formats.
http://dev.virtualearth.net/REST/v1/Locations?CountryRegion=US&adminDistrict=WA&locality=Somewhere&postalCode=98001&addressLine=100%20Main%20St.&key={BingMapsAPIKey}
Find a Location by Query query: http://dev.virtualearth.net/REST/v1/Locations?q=100%20Main%20St.%20Somewhere,%20WA%2098001&key={BingMapsAPIKey}
API Parameters
Note
See the Common Parameters and Types section for additional common parameters to use with these URLs.
Common parameters include:
- Output Parameters: Includes response output types and the JSON callback parameters.
- Culture Parameter: Includes a list of the supported cultures.
- User Context Parameters: Includes parameters that set user location and viewport values to help with determining locations. For example, you can specify the user’s location to prioritize the set of locations returned when you query with incomplete address information.
Parameter values are not case-sensitive.
| Parameters | Alias | Description | Values |
|---|---|---|---|
adminDistrict | Optional for unstructured URL. The subdivision name in the country or region for an address. This element is typically treated as the first order administrative subdivision, but in some cases it is the second, third, or fourth order subdivision in a country, dependency, or region. | A string that contains a subdivision, such as the abbreviation of a US state. Example: WA | |
locality | Optional for unstructured URL. The locality, such as the city or neighborhood, that corresponds to an address. | A string that contains the locality, such as a US city. Example: Seattle | |
postalCode | Optional for unstructured URL. The post code, postal code, or ZIP Code of an address. | A string that contains the postal code, such as a US ZIP Code. Example: 98178 | |
addressLine | Optional for unstructured URL. The official street line of an address relative to the area, as specified by the Locality, or PostalCode, properties. Typical use of this element would be to provide a street address or any official address. | A string specifying the street line of an address. Example: 1 Microsoft Way | |
countryRegion | Optional for unstructured URL. The ISO country code for the country. | A string specifying the ISO country code. Example: AU | |
includeNeighborhood | inclnb | Optional. Specifies to include the neighborhood in the response when it is available. Note: When you create your URL request, you can set the Locality parameter to a neighborhood. In this case, the neighborhood you provide may be returned in the neighborhood field of the response and a greater locality may be returned in the locality field. For example, you can create a request that specifies to include neighborhood information ( inclnb=1) and that sets the Locality to Ballard and the AdminDistrict to WA (Washington State). In this case, the neighborhood field in the response is set to Ballard and the locality field is set to Seattle. You can find this example in the Examples section. | One of the following values: - 1: Include neighborhood information when available.- 0[default]: Do not include neighborhood information.Example: inclnb=1 |
include | incl | Optional. Specifies additional values to include. | The only value for this parameter is ciso2. When you specify include=ciso2, the two-letter ISO country code is included for addresses in the response.Example: incl=ciso2 |
maxResults | maxRes | Optional. Specifies the maximum number of locations to return in the response. | A string that contains an integer between 1 and 20. The default value is 5. Example: maxResults=10 |
Response
One or more Location resources are returned in the response when you make a request by using these URL templates. For more information about the Location resource, see Location Data. For more information about the common response syntax for the Bing Maps REST Services, see Common Response Description. Responses are provided for some URL examples in the following section.
These URLs support JSON (application/json) and XML (application/xml) response formats. A JSON response is provided by default unless you request XML output by setting the output (o) parameter. For more information, see Output Parameters.
Examples
Find location information for a United States street address including the ZIP Code
This example provides location information for a street address in the United States and requests the results in XML format.
XML Response
The Locations resource returned for this example provides the latitude and longitude of the location and defines a geographical area (bounding box) that includes the location. The location entity type is defined as an Address and the address information that was used as input parameters is included and enhanced by adding the county (AdminDistrict2) and ZIP Code.
JSON Response
The following JSON response contains the same information as the previous XML response and is provided when the output (o) parameter is not set.
Find location information for a United States street address without a postal code
This example provides location information for the same street address as the previous example, but does not specify the ZIP Code.
Find location information and request up to 10 location results in the response
This example provides location information for the locality 'Greenville' and requests up to 10 location results in the response. The default maximum number of locations returned is five (5) results.
Find location information by using a structured URL where some parameters have no value
This example provides location information for the United States and uses hyphens (-) for address values that are not specified.
Find location information by using an unstructured URL and setting the userLocation parameter
This example provides location information for an unstructured query for Kings Road in the United Kingdom and uses the userLocation value to prioritize the response. If you remove the userLocation parameter in this example, the results change because the userLocation position prioritizes results that are closer to this location. For more information about the userLocation parameter and other user context parameters, see User Context Parameters.
Find location information and request neighborhood information in the response
This example provides location information for Ballard in Washington state (WA) and also returns neighborhood information. Ballard is a neighborhood, but is specified as a locality in the request. Note that in the response, Ballard is defined as the neighborhood and Seattle is defined as the locality.
XML Response
JSON Response
The following JSON response contains the same information as the previous XML response and is provided when the output (o) parameter is not set.
Find location information for Canada
This example provides location information for a street in Vancouver, Canada.
Find location information for France
This example provides location information for a street in Paris, France.
Find location information for Germany
This example provides location information for an address in Berlin, Germany.
Find location information for the United Kingdom
Dev.virtualearth.net Rest Json Example
These examples provide location information for a postal code in the United Kingdom.
Find location information by using an unstructured URL
These examples provide location information based on the specified parameter values.
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.
- 200
When the request is not successful, the response returns one of the following errors.
- 400
- 401
- 404
- 429
- 500
- 503
See Also
Dev.virtualearth.net Rest Json File
Using the REST Services with .NET
JSON Data Contracts
Geocoding a LocationGetting Route Directions
Find a location by query