Vous êtes sur la page 1sur 453

Contents

Bing Maps REST Services Getting Started with the Bing Maps REST Services What's New in the REST Services Getting Traffic Incident Data Using the REST Services with .NET Locations API Find a Location by Address Find a Location by Point Find a Location by Query Location Data Elevations API Get Elevations Elevation Data Point Compression Algorithm Imagery API Get a Static Map Get Imagery Metadata Imagery Metadata Static Map Data Routes API Calculate a Route Driving Route Example Walking Route Example Transit Route Example Driving Route with Route Path Example Driving Route using Tolerances Example Calculate Routes from Major Roads Route Data Maneuver Types Warning Types Traffic API Get Traffic Incidents Traffic Incident Data Common Parameters and Types Bing Maps REST URL Structure Culture Parameter Output Parameters User Context Parameters

3

4

5

6

11

17

17

33

43

60

71

72

86

91

97

97

121

133

138

147

148

158

181

213

240

289

296

336

353

356

357

358

369

376

376

378

379

382

Location and Area Types

383

Pushpin Syntax and Icon Styles

385

Entity Types

398

Supported Culture Codes

409

Common Response Description

414

JSON Data Contracts

418

Status Codes and Error Handling

451

Developer Resources

453

Bing Maps REST Services

The Bing™ Maps REST Services Application Programming Interface (API) provides a Representational State Transfer (REST) interface to perform tasks such as creating a static map with pushpins, geocoding an address, retrieving imagery metadata, or creating a route.

Transaction accounting is provided when you use the Bing Maps REST Services. For more information about billable and non-billable transactions for the Bing Maps REST Services, see Viewing Bing Maps Transaction Reports.

For information about geocoding large sets of spatial data using a REST Interface, see the Bing Spatial Data Services.

If you are reading this documentation online, you can download the Bing Maps REST Services documentation CHM file or PDF file for offline viewing.

In This Section

Getting Started with the Bing Maps REST Services

Get started with the Bing Maps REST Services.

What's New in the REST Services

Find out about the latest updates to the Bing Maps REST Services.

Getting Traffic Incident Data

Learn how to get traffic incident data by using the Routes API and the Traffic API.

Using the REST Services with .NET

Use the article to learn how to interact with the Bing Maps REST Services APIs using .NET

Locations API

Use the Locations API to geocode and reverse- geocode location data.

Elevations API

Use the Elevations API to get elevation information for a set of locations, polyline or area on the Earth.

Imagery API

Use the Imagery API to get a map with your specifications or if you want to request imagery data such as map tile URLs and imagery provider information.

Routes API

Use the Routes API to get directions and route information for driving, walking or using transit.

Traffic API

Use the Traffic API to get information about

 

traffic incidents and issues in a specified area.

Common Parameters and Types

Use common parameters and types to specify values such as culture and pushpin styles.

Common Response Description

Use this description to understand the results returned for a Bing Maps REST Services request.

Status Codes and Error Handling

Use the status and error code descriptions for troubleshooting.

Developer Resources

Resources and support for the Bing Maps REST Services.

See Also

Getting Started with the Bing Maps REST Services

The Bing™ Maps REST Services Application Programming Interface (API) is a Representational State Transfer (REST) API that you can use to do common tasks, such as finding an address, retrieving a map with a pushpin and a label, or getting driving directions. You perform these tasks by constructing a URL

To use the Bing Maps REST Services, you must have a Bing Maps Key.

Bing Maps REST Services

The following table lists the Bing Maps REST Services and the common tasks they perform. Click the links for API details.

REST API

Features

Locations API



Find a location based on an address, point, or query.

Elevations API



Get the elevations for a set of locations, a path, or an area on the Earth.

Imagery API



Get a static map.



Get a static map that displays a route.



Get imagery metadata.

Routes API



Find a walking, driving or transit route.



Find routes from major routes to a location.

REST API

Features

 



Get traffic information along a route.

Traffic API



Get traffic information for a geographical area.

Additional Topics

The following topics show examples of how to use the Bing Maps REST Services with other Bing Maps APIs or provide related information.

This topic shows how to use the Bing Maps REST Services with Bing Maps AJAX Control, Version 7.0.

This article shows how to write a PHP application that can interact with the Bing Maps REST Services APIs.

Provides a list of transit agencies that are used by Bing Maps REST Services to provide transit routes.

Transaction Accounting

Transactions are counted for each Bing Maps REST Services request sent with a valid Bing Maps Key. For information about billable and non-billable transactions for the Bing Maps REST Services, see Viewing Bing Maps Usage Reports.

What's New in the REST Services

The Bing Maps REST Services contains the following new features.

NEW Elevations API [Get Elevations]

This new API returns elevations for locations on the Earth. You can request elevations for:



A set of locations.



Locations along a polyline you define, such as the coordinates of a road or hiking trail.



Locations within a rectangular area that is defined by pairs of latitudes and longitudes.

You can request elevations based on the ellipsoid model of the Earth (WGS84) or the geoid sea level mode (EGM2008 2.5’). The ellipsoid model is equivalent to GPS altitude and the geoid sea level model is what is commonly known as altitude above sea level. For more information about these models, see the Earth Models and Zoom Level section in the Get Elevations topic.

Expanded language coverage for Routes API and Locations API (Geocoding)



The Bing Maps REST Services has significantly expanded its language coverage when you geocode locations or create routes. For a list of supported language codes to use with the culture parameter, see Supported Culture Codes.

Getting Traffic Incident Data

You can get traffic incident information along a route using the Routes API and for a geographical area by using the Traffic API. Traffic incident information is provided in two ways:



Traffic incident details including description, severity, location, type of incident.



Traffic location codes that specify incident information for a road segment or specific location as a code, such as 120-15918. A subscription is typically required to interpret and use the traffic location codes.

For traffic coverage by country, see Bing Maps Traffic Coverage.

Traffic incident information along a route (Routes API)

Each route segment (itinerary item) returned by the Routes API may include a set of traffic location codes and a set of warnings that specify traffic incident information along that part of the route. The warnings include a description of the incident, the severity, and a warning type, such as Accident or BlockedRoad. To see a list of the warning types, see Warning Types.

There is no specific correlation between traffic location codes and warnings. For example, an itinerary item can contain traffic location codes without corresponding warnings.

The following is an example of an itinerary item that contains both warnings and traffic location codes.

{

"itineraryItems":[

{

"compassDirection":"south",

"details":[

{

"compassDegrees":180,

"endPathIndices":[

],

1

"locationCodes":[

"114-08912",

"114-08911"

],

"maneuverType":"DepartStart",

"mode":"Driving",

"names":[

"44TH Ave W"

],

"roadType":"Arterial",

"startPathIndices":[

],

}

]

0

"exit":"",

"iconType":"Auto",

"instruction":{

"maneuverType":"DepartStart",

"text":"Depart 44TH Ave W toward 192ND St SW"

},

"maneuverPoint":{

"type":"Point",

"coordinates":[

47.825321,

-122.292407

},

]

"sideOfStreet":"Unknown",

"tollZone":"",

"towardsRoadName":"192ND St SW",

"transitTerminus":"",

"travelDistance":1.029,

"travelDuration":97,

"travelMode":"Driving"

},

{

"compassDirection":"southwest",

"details":[

{

 

"compassDegrees":217,

"endPathIndices":[

6

],

"maneuverType":"TakeRampRight",

"mode":"Driving",

"roadType":"Ramp",

"startPathIndices":[

1

]

},

{

"compassDegrees":241,

"endPathIndices":[

],

91

"locationCodes":[

"114-04212",

"114N04212",

"114-04211",

"114N04211",

"114N04207",

"114-04195"

],

"maneuverType":"Merge",

"mode":"Driving",

"names":[

"I-5 South"

],

"roadShieldRequestParameters":{

"bucket":50402,

"shields":[

{

"labels":[

],

"5"

"roadShieldType":1

},

]

}

"roadType":"LimitedAccessHighway",

"startPathIndices":[

],

}

]

6

"exit":"",

"iconType":"Auto",

"instruction":{

"maneuverType":"RampThenHighwayRight",

"text":"Take ramp right for I-5 South"

},

"maneuverPoint":{

"type":"Point",

"coordinates":[

47.816019,

-122.292332

},

]

"sideOfStreet":"Unknown",

"tollZone":"",

"transitTerminus":"",

"travelDistance":24.323,

"travelDuration":908,

"travelMode":"Driving",

"warnings":[

{

"severity":"Minor",

"text":"Minor Congestion: slow 1st Av\/Northgate Way (#173) to Express Lanes Southern Entrance\/Exit",

"warningType":"Congestion"

}

]

}

]

}

Traffic incident information within a geographical area (Traffic API)

The Traffic API returns a list of traffic incidents in a geographical area and provides incident details and traffic location codes. Traffic incident details include information such as the incident description, severity, location, road closures, type of incident, time of incident and detours. See Traffic Incident Data for a list of the incident details that may be returned. Traffic incidents reported by the Traffic API include common traffic problems, such as accidents and disabled vehicles, as well as other potential causes of traffic, such as sports events.

To use the Traffic API, you must specify an area defined as a bounding box. A bounding box is a set of longitudes and latitudes that define an area. See Location and Area Types for more information about a bounding box.

The following is an example of traffic incident information returned in a JSON Traffic API response.

{

" type":"TrafficIncident:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",

"point":{

"type":"Point",

"coordinates":[

38.64829,

-94.36405

},

]

"congestion":"",

"description":"in both directions between MO-2\/MO-7 and MO-291\/Cantrell Rd - construction",

"detour":"",

"end":"\/Date(1316217600000)\/",

"incidentId":214828828,

"lane":"Total Lanes lane blocked",

"lastModified":"\/Date(1310385750290)\/",

"roadClosed":false,

"severity":2,

"start":"\/Date(1310126400000)\/",

"toPoint":{

"type":"Point",

"coordinates":[

 

38.65831,

-94.36706

]

},

"locationCodes":[

"119+05041",

"119+05042",

"119-05041",

"119-05042",

"119N05041",

"119N05042",

"119P05041",

"119P05042"

],

"type":9,

"verified":true

}

Using the REST Services with .NET

This article will describe how to interact with the Bing Maps REST Services APIs using .NET. This approach can be used with technologies such as Windows Store apps and Windows Presentation Foundation (WPF).

The Bing Maps REST Services are a set of RESTful web services that access collection of resources by using a URL and the HTTP GET and POST methods The size of REST responses tend to be significantly smaller than SOAP-based service responses, and reduce the amount of time it takes a client application to download the response data. This increase in efficiency becomes especially important when developing mobile applications.

Each Bing Maps REST Services request is made using a URI and additional query parameters that specify the information to return. Some REST Services APIs support HTTP POST requests that you can use when the query parameter data increases the URL length beyond browser limits. You can specify XML or JSON format for the response. A JSON response is typically 25%- 40% smaller than an XML response, and will take less time for the client to download. This topic focuses on JSON responses only.

Making use of sessions

All Bing Maps REST Services require a Bing Maps Key. If you are using the Bing Maps REST Services with one of the Bing Maps controls, such as AJAX, WPF, Windows Store app SDK, you can use a Bing Maps key as a session key. A session key can be used for all requests to the Bing Maps REST Services. The benefit of using a session key is that you are billed for one transaction per session and all calls to the REST services within that session are non-billable. For more information about billed transactions, see Viewing Bing Maps Usage Reports.

The following examples show how to create a session key from an instance of Bing Maps control using .NET.

Map.CredentialsProvider.GetCredentials((c) =>

{

 

string sessionKey = c.ApplicationId;

//Generate a request URL for the Bing Maps REST services.

//Use the session key in the request as the Bing Maps key

});

Map.CredentialsProvider.GetCredentials(

Function(c)

Dim sessionKey As String = c.ApplicationId

'Generate a request URL for the Bing Maps REST services.

'Use the session key in the request as the Bing Maps key

Return 0

End Function)

Making the request

To access the Bing Maps REST Services, you create a URL request and then submit the request using HTTP GET or POST protocol . When the response data is returned, you must serialize the data against a set of data contracts. The data contracts for the Bing Maps REST Services are quite large and have been included at the end of this topic. As the Bing Maps REST Services adds new functionality, these data contracts must be updated. A benefit of working with JSON serialization rather than XML serialization is that changes in the schema rarely cause issues for existing applications. For instance, if a new property is added to the Bing Maps REST Services, an application that uses the old data contracts can still process a response without errors; however, the new property will not be available. To get the new property, you must update the data contracts.

In order to make use of JSON serialization in .NET, use the DataContractJsonSerializer by referencing the following libraries in your project:

 System.Runtime.Serialization

 System.ServiceModel.Web

When you specify parameter data for a Bing Maps REST service request, it is a good practice to encode the parameter values. This becomes especially important when working with special characters. In the following code samples, we use the Uri class that encodes these parameters automatically.

HTTP GET Requests

The following example is a generic method that can be used to make GET requests with Bing Maps REST Services.

private void GetResponse(Uri uri, Action<Response> callback)

{

WebClient wc = new WebClient();

wc.OpenReadCompleted += (o, a) =>

{

if (callback != null)

{

DataContractJsonSerializer ser = new DataContractJsonSerializer(typeof(Response));

callback(ser.ReadObject(a.Result) as Response);

};

}

wc.OpenReadAsync(uri);

}

Private Sub GetResponse(uri As Uri, callback As Action(Of Response))

Dim wc As New WebClient()

AddHandler wc.OpenReadCompleted,

Function(o, a)

If callback IsNot Nothing Then

Dim ser As New DataContractJsonSerializer(GetType(Response))

callback(TryCast(ser.ReadObject(a.Result), Response))

End If

Return 0

End Function

wc.OpenReadAsync(uri)

End Sub

HTTP POST Requests

The following example is a generic method that can be used to make HTTP POST requests with Bing Maps REST Services for APIs that support HTTP POST protocol.

private void GetPOSTResponse(Uri uri, string data, Action<Response> callback)

{

HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(uri);

request.Method = "POST";

request.ContentType = "text/plain;charset=utf-8";

System.Text.UTF8Encoding encoding = new System.Text.UTF8Encoding();

byte[] bytes = encoding.GetBytes(data);

request.ContentLength = bytes.Length;

using (Stream requestStream = request.GetRequestStream())

{

 

// Send the data.

requestStream.Write(bytes, 0, bytes.Length);

}

request.BeginGetResponse((x) =>

{

using (HttpWebResponse response = (HttpWebResponse)request.EndGetResponse(x))

{

if (callback != null)

{

DataContractJsonSerializer ser = new DataContractJsonSerializer(typeof(Response));

callback(ser.ReadObject(response.GetResponseStream()) as Response);

}

}

}, null);

}

Private Sub GetPOSTResponse(uri As Uri, data As String, callback As Action(Of Response))

Dim request As HttpWebRequest = DirectCast(HttpWebRequest.Create(uri), HttpWebRequest)

request.Method = "POST"

request.ContentType = "text/plain;charset=utf-8"

Dim encoding As New System.Text.UTF8Encoding()

Dim bytes As Byte() = encoding.GetBytes(data)

request.ContentLength = bytes.Length

Using requestStream As Stream = request.GetRequestStream()

' Send the data.

requestStream.Write(bytes, 0, bytes.Length)

End Using

request.BeginGetResponse(

Function(x)

Using response As HttpWebResponse = DirectCast(request.EndGetResponse(x), HttpWebResponse)

If callback IsNot Nothing Then

Dim ser As New DataContractJsonSerializer(GetType(Response))

callback(TryCast(ser.ReadObject(response.GetResponseStream()),

Response))

End If

End Using

Return 0

End Function, Nothing)

End Sub

Implementing a request

The following is an example of how to use the above generic methods to make an HTTP GET request to the Bing Maps REST Services. This example geocodes the address “1 Microsoft Way, Redmond, WA”.

string key = "YOUR_BING_MAPS_KEY or SESSION_KEY";

string query = "1 Microsoft Way, Redmond, WA";

Uri geocodeRequest = new Uri(string.Format("http://dev.virtualearth.net/REST/v1/Locations?q={0}&key={1}", query, key));

GetResponse(geocodeRequest, (x) =>

{

 

Console.WriteLine(x.ResourceSets[0].Resources.Length + " result(s) found.");

Console.ReadLine();

});

Dim key As String = "YOUR_BING_MAPS_KEY or SESSION_KEY"

Dim query As String = "1 Microsoft Way, Redmond, WA"

Dim geocodeRequest As New Uri(String.Format("http://dev.virtualearth.net/REST/v1/Locations?q={0}&key={1}", query, key))

GetResponse(geocodeRequest, Function(x)

Console.WriteLine(x.ResourceSets(0).Resources.Length + " result(s) found.")

Console.ReadLine()

Return 0

End Function)

Data Contracts

The data contracts for the Bing Maps REST Services are large but straight forward. All classes need to have a DataContract attribute, and all public properties that are to be serialized need to have a DataMember attribute, and both a getter and a setter in C#. See JSON Data Contracts for the latest set of contracts.

Locations API

Use the Locations API to get location information.

For an example of how to use the Locations API with Bing Maps AJAX Control 7.0, see Displaying Location Search Results Using the REST Services.

In this section

Find a Location by Address

Use these URL templates to get latitude and longitude coordinates for a location by specifying values such as a locality, postal code, and street address.

Find a Location by Point

Use this URL template to get the location information associated with latitude and longitude coordinates.

Find a Location by Query

Use these URL templates to get latitude and longitude coordinates that correspond to location information provided as a query string.

Location Data

Use this description to understand the results returned in the response to a Locations API request.

See Also

Find a Location by Address

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

and response values in the Examples section. URL Templates These templates support both HTTP and HTTPS

These templates support both HTTP and HTTPS protocols.

You can increase the accuracy of a location result by specifying an IP address, user location or map area in the URL request. For more information about these parameters, see User Context Parameters.

Structured URLs: Get the latitude and longitude coordinates based on a set of address values for specific countries

based on a set of address values for specific countries You can substitute a hyphen (-)

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.

A structured URL specifies the location data for the country as part of the URL path.

Canada

http://dev.virtualearth.net/REST/v1/Locations/CA/adminDistrict/postalCode/locality/addres

sLine?includeNeighborhood=includeNeighborhood&maxResults=maxResults&key=BingMapsKey

France

http://dev.virtualearth.net/REST/v1/Locations/FR/postalCode/locality/addressLine?includeN

eighborhood=includeNeighborhood&maxResults=maxResults&key=BingMapsKey

Germany

http://dev.virtualearth.net/REST/v1/Locations/DE/postalCode/locality/addressLine?includeN

eighborhood=includeNeighborhood&maxResults=maxResults&key=BingMapsKey

United Kingdom

http://dev.virtualearth.net/REST/v1/Locations/UK/postalCode?includeNeighborhood=includeNe

ighborhood&maxResults=maxResults&key=BingMapsKey

United States

http://dev.virtualearth.net/REST/v1/Locations/US/adminDistrict/postalCode/locality/addres

sLine?includeNeighborhood=includeNeighborhood&maxResults=maxResults&key=BingMapsKey

http://dev.virtualearth.net/REST/v1/Locations/US/adminDistrict/locality/addressLine?inclu

deNeighborhood=includeNeighborhood&maxResults=maxResults&key=BingMapsKey

Unstructured URL: Get the latitude and longitude coordinates based on a set of address values for any country

You can get information for a location in any country by setting one or more of the parameters in the following URL.

An unstructured 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.

http://dev.virtualearth.net/REST/v1/Locations?countryRegion=countryRegion&adminDistrict=a

dminDistrict&locality=locality&postalCode=postalCode&addressLine=addressLine&userLocation

=userLocation&userIp=userIp&usermapView=usermapView&includeNeighborhood=includeNeighborho

od&maxResults=maxResults&key=BingMapsKey

  About Special Characters When you specify location information using one of the structured URLs,
 

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

parameter value in a structured URL. If the location information contains any special characters, use the Unstructured URL template or the Find a Location by Query API.

a

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.

Unstructured query:

http://dev.virtualearth.net/REST/v1/Locations?CountryRegion=US&adminDistrict=WA&lo

cality=Somewhere&postalCode=98001&addressLine=100%20Main%20St.&key= BingMapsKey

Find a Location by Query query:

http://dev.virtualearth.net/REST/v1/Locations?q=100%20Main%20St.%20Somewhere,%20WA

%2098001&key=BingMapsKey

query : http://dev.virtualearth.net/REST/v1/Locations?q=100%20Main%20St.%20Somewhere,%20WA %2098001&key= BingMapsKey

You can increase the accuracy of a location result by specifying an IP address, user location or map area in the URL request. For more information about these parameters, see User Context Parameters.

If you are using the Locations API from server-side code, you can set the userIP

parameter to 127.0.0.1 (localhost) to prevent the server’s location from affecting the location search results.

Template Parameters

(localhost) to prevent the server’s location from affecting the location search results. Template Parameters 19

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

A

string specifying

the street line of an address.

Example: 1 Microsoft

Way

Parameters

Alias

Description

Values

   

street address or any official address.

 

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.

One of the following values:



1: Include

neighborhood

When you create your URL request, you can set the Locality parameter to a neighborhood.

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

information when

available.



0 [default]: Do not include neighborhood information.

Example:

inclnb=1

 

Parameters

Alias

Description

Values

   

response is set to Ballard and the locality field is set to Seattle. You can find this example in the Examples section.

 

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.

http://dev.virtualearth.net/REST/v1/Locations/US/WA/98052/Redmond/1%20Microsoft%20Way?o=x

ml&key=BingMapsKey

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.

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">

<Copyright>

Copyright © 2011 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>

558732d648204c958546678579cbc5cb

</TraceId>

<ResourceSets>

<ResourceSet>

<EstimatedTotal>1</EstimatedTotal>

<Resources>

<Location>

<Name>1 Microsoft Way, Redmond, WA 98052</Name>

<Point>

<Latitude>47.640120461583138</Latitude>

<Longitude>-122.12971039116383</Longitude>

</Point>

<BoundingBox>

<SouthLatitude>47.636257744012461</SouthLatitude>

<WestLongitude>-122.13735364288299</WestLongitude>

<NorthLatitude>47.643983179153814</NorthLatitude>

<EastLongitude>-122.12206713944467</EastLongitude>

</BoundingBox>

<EntityType>Address</EntityType>

<Address>

<AddressLine>1 Microsoft Way</AddressLine>

<AdminDistrict>WA</AdminDistrict>

<AdminDistrict2>King Co.</AdminDistrict2>

<CountryRegion>United States</CountryRegion>

<FormattedAddress>1 Microsoft Way, Redmond, WA 98052</FormattedAddress>

<Locality>Redmond</Locality>

<PostalCode>98052</PostalCode>

</Address>

<Confidence>High</Confidence>

<MatchCode>Good</MatchCode>

<GeocodePoint>

<Latitude>47.640120461583138</Latitude>

<Longitude>-122.12971039116383</Longitude>

<CalculationMethod>InterpolationOffset</CalculationMethod>

<UsageType>Display</UsageType>

</GeocodePoint>

<GeocodePoint>

<Latitude>47.640144601464272</Latitude>

<Longitude>-122.12976671755314</Longitude>

<CalculationMethod>Interpolation</CalculationMethod>

<UsageType>Route</UsageType>

</GeocodePoint>

</Location>

</Resources>

</ResourceSet>

</ResourceSets>

</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.

{

"authenticationResultCode":"ValidCredentials",

"brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",

"copyright":"Copyright © 2011 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":"Location:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",

"bbox":[

47.636257744012461,

-122.13735364288299,

47.643983179153814,

-122.12206713944467

],

"name":"1 Microsoft Way, Redmond, WA 98052",

"point":{

"type":"Point",

"coordinates":[

47.640120461583138,

-122.12971039116383

},

]

"address":{

"addressLine":"1 Microsoft Way",

"adminDistrict":"WA",

"adminDistrict2":"King Co.",

"countryRegion":"United States",

"formattedAddress":"1 Microsoft Way, Redmond, WA 98052",

"locality":"Redmond",

"postalCode":"98052"

},

"confidence":"High",

"entityType":"Address",

"geocodePoints":[

{

 

"type":"Point",

"coordinates":[

47.640120461583138,

-122.12971039116383

],

"calculationMethod":"InterpolationOffset",

"usageTypes":[

"Display"

]

},

{

 

"type":"Point",

"coordinates":[

47.640144601464272,

-122.12976671755314

],

"calculationMethod":"Interpolation",

"usageTypes":[

"Route"

]

}

],

}

]

],

"matchCodes":[

}

]

"Good"

"statusCode":200,

"statusDescription":"OK",

"traceId":"b0b1286504404eafa7e7dad3e749d570"

}

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.

http://dev.virtualearth.net/REST/v1/Locations/US/WA/Redmond/1%20Microsoft%20Way?output=xm

l&key=BingMapsKey

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.

http://dev.virtualearth.net/REST/v1/Locations?locality=Greenville&maxResults=10&key=BingM

apsKey

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.

http://dev.virtualearth.net/REST/v1/Locations/US/-/-/-?key=BingMapsKey

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.

http://dev.virtualearth.net/REST/v1/Locations?culture=en-

GB&addressLine=Kings%20Road&o=xml&userLocation=51.504360719046616,-

0.12600176611298197&key=BingMapsKey

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.

http://dev.virtualearth.net/REST/v1/Locations/US/WA/-/Ballard/-

?o=xml&inclnb=1&key=BingMapsKey

XML Response

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">

<Copyright>

Copyright © 2011 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>

ce2998ccf7dc4985b689b091fb64b3e5

</TraceId>

<ResourceSets>

<ResourceSet>

<EstimatedTotal>1</EstimatedTotal>

<Resources>

<Location>

<Name>Ballard, WA</Name>

<Point>

<Latitude>47.675968170166016</Latitude>

<Longitude>-122.38591003417969</Longitude>

</Point>

<BoundingBox>

<SouthLatitude>47.6561164855957</SouthLatitude>

<WestLongitude>-122.41252899169922</WestLongitude>

<NorthLatitude>47.697746276855469</NorthLatitude>

<EastLongitude>-122.36044311523438</EastLongitude>

</BoundingBox>

<EntityType>Neighborhood</EntityType>

<Address>

<AdminDistrict>WA</AdminDistrict>

<AdminDistrict2>King Co.</AdminDistrict2>

<CountryRegion>United States</CountryRegion>

<FormattedAddress>Ballard, WA</FormattedAddress>

<Locality>Seattle</Locality>

<Neighborhood>Ballard</Neighborhood>

</Address>

<Confidence>High</Confidence>

<MatchCode>Good</MatchCode>

<GeocodePoint>

<Latitude>47.675968170166016</Latitude>

<Longitude>-122.38591003417969</Longitude>

<CalculationMethod>Rooftop</CalculationMethod>

<UsageType>Display</UsageType>

</GeocodePoint>

</Location>

</Resources>

</ResourceSet>

</ResourceSets>

</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.

{

"authenticationResultCode":"ValidCredentials",

"brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",

"copyright":"Copyright © 2011 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":"Location:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",

"bbox":[

47.6561164855957,

-122.41252899169922,

47.697746276855469,

-122.36044311523438

],

"name":"Ballard, WA",

"point":{

"type":"Point",

"coordinates":[

47.675968170166016,

-122.38591003417969

},

]

"address":{

"adminDistrict":"WA",

"adminDistrict2":"King Co.",

"countryRegion":"United States",

"formattedAddress":"Ballard, WA",

"locality":"Seattle",

"neighborhood":"Ballard"

},

"confidence":"High",

"entityType":"Neighborhood",

"geocodePoints":[

{

 

"type":"Point",

"coordinates":[

47.675968170166016,

-122.38591003417969

],

"calculationMethod":"Rooftop",

"usageTypes":[

"Display"

]

}

],

}

]

],

"matchCodes":[

}

]

"Good"

"statusCode":200,

"statusDescription":"OK",

"traceId":"0fa6626c9aae482e968c45e465862f93"

}

Find location information for Canada. This example provides location information for a street in Vancouver, Canada.

http://dev.virtualearth.net/REST/v1/Locations/CA/BC/V6G/Vancouver/Stanley%20Park%20Causew

ay?key=BingMapsKey

Find location information for France. This example provides location information for a street in Paris, France.

http://dev.virtualearth.net/REST/v1/Locations/FR/75007/Paris/Avenue%20Gustave%20Eiffel?ke

y=BingMapsKey

Find location information for Germany. This example provides location information for an address in Berlin, Germany.

http://dev.virtualearth.net/REST/v1/Locations/DE/12010/Berlin/Platz%20Der%20Luftbrücke%20

5?key=BingMapsKey

Find location information for the United Kingdom. These examples provide location information for a postal code in the United Kingdom.

http://dev.virtualearth.net/REST/v1/Locations/GB/SW1A?key=BingMapsKey

http://dev.virtualearth.net/REST/v1/Locations/GB/SW1A%202AA?key=BingMapsKey

Find location information by using an unstructured URL. These examples provide location information based on the specified parameter values.

http://dev.virtualearth.net/REST/v1/Locations?postalCode=98052&key=BingMapsKey

http://dev.virtualearth.net/REST/v1/Locations?locality=Redmond&adminDistrict=WA&key=BingM

apsKey

http://dev.virtualearth.net/REST/v1/Locations?countryRegion=AU&adminDistrict=WA&key=BingM

apsKey

http://dev.virtualearth.net/REST/v1/Locations?locality=London&postalCode=SW1A&key=BingMap

sKey

HTTP Status Codes

BingMap sKey HTTP Status Codes For more details about these HTTP status codes, see Status

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.

200



400



401



500



503

Find a Location by Point

Use the following URL template to get the location information associated with latitude and longitude coordinates.

When you make a request by using the following URL template, the response returns one or more Location resources that contain location information associated with the latitude and longitude coordinate values that you specify. Location information can be as specific as an address or more general such as the country or region. You can specify the type of location information you want to receive by setting the includeEntityTypes parameter in the URL. For example, you can specify to only receive information about the neighborhood that corresponds to the coordinates. 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 Template

and response values in the Examples section. URL Template This template supports both HTTP and HTTPS

This template supports both HTTP and HTTPS protocols.

Get an address for a specified point (latitude and longitude).

http://dev.virtualearth.net/REST/v1/Locations/point?includeEntityTypes=entityTypes&includ

eNeighborhood=includeNeighborhood&key=BingMapsKey

Template Parameters

&key= BingMapsKey Template Parameters See the Common Parameters and Types section for additional

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.

Parameter values are not case-sensitive.

Parameters

Alias

Description

Values

includeEntityTypes

 

Optional.

A comma separated

Parameters Alias Description Values Specifies the entity types that you want to return in the
Parameters
Alias
Description
Values
Specifies the
entity types that
you want to
return in the
response. Only
the types you
specify will be
returned. If the
point cannot be
mapped to the
list of entity types
selected from the
following options.
 Address
 Neighborhood
 PopulatedPlace
 Postcode1
 AdminDivision1
 AdminDivision2
entity types you
specify, no
location
information is
returned in the
response.
 CountryRegion
These entity types are
ordered from the most
specific entity to the
least specific entity.
When entities of more
than one entity type
are found, only the
most specific entity is
returned. For
example, if you
specify Address and
AdminDistrict1 as
entity types and
entities were found for
both types, only the
Address entity
information is
returned in the
response. One
exception to this rule
is when both
PopulatedPlace and
Neighborhood entity
types are specified
and information is
found for both. In this
case, the information
for both entity types is
returned. Also, more
than one
Parameters Alias Description Values Neighborhood may be returned because the area covered by two different
Parameters
Alias
Description
Values
Neighborhood may be
returned because the
area covered by two
different
neighborhoods can
overlap.
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
includeNeighborhood
inclnb
Optional.
Specifies to
include the
neighborhood in
the response
One of the following
values:

1: Include
neighborhood
information when
when it is
available.
available.

0 [default]: Do
not include
neighborhood
information.
Example:
inclnb=1

Response

One or more Location resources are returned in the response when you make a request using this URL template. 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. JSON and XML responses are provided for the URL example in the following section.

This URL supports 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 specified point on the Earth.

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

http://dev.virtualearth.net/REST/v1/Locations/47.64054,-122.12934?o=xml&key=BingMapsKey

XML Response

This example returns the following XML response.

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">

<Copyright>

Copyright © 2011 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>

dd31ffaf098f4406b7ecdd0da36680ff

</TraceId>

<ResourceSets>

<ResourceSet>

<EstimatedTotal>1</EstimatedTotal>

<Resources>

<Location>

<Name>1 Microsoft Way, Redmond, WA 98052</Name>

<Point>

<Latitude>47.640568390488625</Latitude>

<Longitude>-122.1293731033802</Longitude>

</Point>

<BoundingBox>

<SouthLatitude>47.636705672917948</SouthLatitude>

<WestLongitude>-122.137016420622</WestLongitude>

<NorthLatitude>47.6444311080593</NorthLatitude>

<EastLongitude>-122.1217297861384</EastLongitude>

</BoundingBox>

<EntityType>Address</EntityType>

<Address>

<AddressLine>1 Microsoft Way</AddressLine>

<AdminDistrict>WA</AdminDistrict>

<AdminDistrict2>King Co.</AdminDistrict2>

<CountryRegion>United States</CountryRegion>

<FormattedAddress>1 Microsoft Way, Redmond, WA 98052</FormattedAddress>

<Locality>Redmond</Locality>

<PostalCode>98052</PostalCode>

</Address>

<Confidence>Medium</Confidence>

<MatchCode>Good</MatchCode>

<GeocodePoint>

<Latitude>47.640568390488625</Latitude>

<Longitude>-122.1293731033802</Longitude>

<CalculationMethod>Interpolation</CalculationMethod>

<UsageType>Display</UsageType>

<UsageType>Route</UsageType>

</GeocodePoint>

</Location>

</Resources>

</ResourceSet>

</ResourceSets>

</Response>

JSON Response

The following JSON response contains the same information as the XML response and is provided when the output (o) parameter is not set.

{

"authenticationResultCode":"ValidCredentials",

"brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",

"copyright":"Copyright © 2011 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":"Location:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",

"bbox":[

47.636705672917948,

-122.137016420622,

47.6444311080593,

-122.1217297861384

],

"name":"1 Microsoft Way, Redmond, WA 98052",

"point":{

"type":"Point",

"coordinates":[

47.640568390488625,

-122.1293731033802

},

]

"address":{

"addressLine":"1 Microsoft Way",

"adminDistrict":"WA",

"adminDistrict2":"King Co.",

"countryRegion":"United States",

"formattedAddress":"1 Microsoft Way, Redmond, WA 98052",

"locality":"Redmond",

"postalCode":"98052"

},

"confidence":"Medium",

"entityType":"Address",

"geocodePoints":[

{

 

"type":"Point",

"coordinates":[

47.640568390488625,

-122.1293731033802

],

"calculationMethod":"Interpolation",

"usageTypes":[

"Display",

"Route"

]

}

],

}

]

],

"matchCodes":[

}

]

"Good"

"statusCode":200,

"statusDescription":"OK",

"traceId":"99b1256e09044490bce82bbbba1dab7a"

}

Find location information for a specified point and request that only CountryRegion entity types be returned.

This example requests only country or region information for the same latitude and longitude as the previous example.

http://dev.virtualearth.net/REST/v1/Locations/47.64054,-

122.12934?includeEntityTypes=countryRegion&o=xml&key=BingMapsKey

XML Response

This example returns the following XML response.

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">

<Copyright>

Copyright © 2011 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>

ca4cc0ce946e4564a20a44db811ee954

</TraceId>

<ResourceSets>

<ResourceSet>

<EstimatedTotal>1</EstimatedTotal>

<Resources>

<Location>

<Name>United States</Name>

<Point>

<Latitude>39.450000762939453</Latitude>

<Longitude>-98.907997131347656</Longitude>

</Point>

<BoundingBox>

<SouthLatitude>26.677207946777344</SouthLatitude>

<WestLongitude>177.3487548828125</WestLongitude>

<NorthLatitude>75.7627944946289</NorthLatitude>

<EastLongitude>-55.848747253417969</EastLongitude>

</BoundingBox>

<EntityType>Sovereign</EntityType>

<Address>

<CountryRegion>United States</CountryRegion>

<FormattedAddress>United States</FormattedAddress>

</Address>

<Confidence>High</Confidence>

<MatchCode>Good</MatchCode>

<GeocodePoint>

<Latitude>39.450000762939453</Latitude>

<Longitude>-98.907997131347656</Longitude>

<CalculationMethod>Rooftop</CalculationMethod>

<UsageType>Display</UsageType>

</GeocodePoint>

</Location>

</Resources>

</ResourceSet>

</ResourceSets>

</Response>

JSON Response

The following JSON response contains the same information as the XML response and is provided when the output (o) parameter is not set.

{

"authenticationResultCode":"ValidCredentials",

"brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",

"copyright":"Copyright © 2011 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":"Location:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",

"bbox":[

26.677207946777344,

177.3487548828125,

75.7627944946289,

-55.848747253417969

],

"name":"United States",

"point":{

"type":"Point",

"coordinates":[

39.450000762939453,

-98.907997131347656

},

]

"address":{

"countryRegion":"United States",

"formattedAddress":"United States"

},

"confidence":"High",

"entityType":"Sovereign",

"geocodePoints":[

{

"type":"Point",

"coordinates":[

39.450000762939453,

-98.907997131347656

],

"calculationMethod":"Rooftop",

"usageTypes":[

],

}

]

],

}

]

"Display"

"matchCodes":[

}

]

"Good"

"statusCode":200,

"statusDescription":"OK",

"traceId":"df80a942ddb3440188d7f97a31979d1a"

}

HTTP Status Codes

} HTTP Status Codes For more details about these HTTP status codes, see Status

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

 500

 503

See Also

Find a Location by Query

Use the following URL templates to get latitude and longitude coordinates that correspond to location information provided as a query string. The strings Space Needle (a landmark) and 1 Microsoft Way Redmond WA (an address) are examples of query strings with location information. These strings can be specified as a structured URL parameter or as a query parameter value.

This URL template can be used to geocode information from any country. For more accurate results, use User Context Parameters, such as the coordinates of a user’s current location.

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 Template

and response values in the Examples section. URL Template These templates support both HTTP and HTTPS

These templates support both HTTP and HTTPS protocols.

You can increase the accuracy of a location result by specifying an IP address, user location or map area in the URL request. For more information about these parameters, see User Context Parameters.

If you are using the Locations API from server-side code, you can set the userIP parameter to 127.0.0.1 (localhost) to prevent the server’s location from affecting the location search results.

Returns latitude and longitude coordinates for a location that is specified as query string.

Structured URL

A structured URL specifies the location data as part of the URL path.

http://dev.virtualearth.net/REST/v1/Locations/locationQuery?includeNeighborhood=includeNe

ighborhood&maxResults=maxResults&include=queryParse&key=BingMapsKey

Unstructured URL

An unstructured URL appends the location data to the URL path. In the following template, the location data is specified by using a query parameter that is appended to the end of the URL path.

http://dev.virtualearth.net/REST/v1/Locations?query=locationQuery&includeNeighborhood=inc

ludeNeighborhood&include=queryParse&maxResults=maxResults&key=BingMapsKey

Template Parameters

maxResults &key= BingMapsKey Template Parameters See the Common Parameters and Types section for additional

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 assist with determining locations. For example, you can prioritize the set of locations returned by a location query when you provide information about the user’s location.

When an alias is provided, you can use the alias to shorten the length of the query parameter. For example, query=1600 Pennsylvania Ave NW Washington, DC can be shortened to q=1600 Pennsylvania Ave NW Washington, DC.

Parameters are not case-sensitive.

Parameters

Alias

Description

 

Values

query

q

Required.

A string that contains information about a location, such as an address or landmark name.

Location

information

Structured URL examples:

.

White%20House

1600%20Pennsylvania%20Ave%20NW%20Washingto

n,%20DC

Unstructured URL examples:

query=White%20House

q=1600%20Pennsylvania%20Ave%20NW%20Washing

ton,%20DC

includeNeighborh

inclnb

Optional.

One of the following values:

ood

Specifies



1: Include neighborhood information when available.

to include

the



0 [default]: Do not include neighborhood information.

neighborho

od with the address information the response when it is

available.

Example:

inclnb=1

include

incl

Optional.

The only option for this parameter is queryParse. When this parameter value is specified, the response shows how the query string was parsed into address values, such as addressLine, locality, adminDistrict, and postalCode.

Specifies

to include

the parsed

query

string

Example: incl=queryParse

values in

the

response.

Parameters

Alias

Description

Values

maxResults

maxR

Optional.

A string that contains an integer between 1 and 20. The default value is 5.

es

Specifies

the

Example:

maximum

maxResults=10

number of

locations to

return in

the

response.

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. JSON and XML responses are provided for the 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 an address using a query string.

The following examples request latitude and longitude information for an address specified by the query string 1 Microsoft way, Redmond WA 98052. Both URLs return the same information. The results are requested in XML format.

http://dev.virtualearth.net/REST/v1/Locations/1%20Microsoft%20Way%20Redmond%20WA%2098052?

o=xml&key=BingMapsKey

http://dev.virtualearth.net/REST/v1/Locations?q=1%20Microsoft%20Way%20Redmond%20WA%209805

2&o=xml&key=BingMapsKey

XML Response

This example returns the following XML response.

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">

<Copyright>

Copyright © 2011 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>

717bea918cca4a7b9a5dabebb6d23c20

</TraceId>

<ResourceSets>

<ResourceSet>

<EstimatedTotal>1</EstimatedTotal>

<Resources>

<Location>

<Name>1 Microsoft Way, Redmond, WA 98052</Name>

<Point>

<Latitude>47.640120461583138</Latitude>

<Longitude>-122.12971039116383</Longitude>

</Point>

<BoundingBox>

<SouthLatitude>47.636257744012461</SouthLatitude>

<WestLongitude>-122.13735364288299</WestLongitude>

<NorthLatitude>47.643983179153814</NorthLatitude>

<EastLongitude>-122.12206713944467</EastLongitude>

</BoundingBox>

<EntityType>Address</EntityType>

<Address>

<AddressLine>1 Microsoft Way</AddressLine>

<AdminDistrict>WA</AdminDistrict>

<AdminDistrict2>King Co.</AdminDistrict2>

<CountryRegion>United States</CountryRegion>

<FormattedAddress>1 Microsoft Way, Redmond, WA 98052</FormattedAddress>

<Locality>Redmond</Locality>

<PostalCode>98052</PostalCode>

</Address>

<Confidence>High</Confidence>

<MatchCode>Good</MatchCode>

<GeocodePoint>

<Latitude>47.640120461583138</Latitude>

<Longitude>-122.12971039116383</Longitude>

<CalculationMethod>InterpolationOffset</CalculationMethod>

<UsageType>Display</UsageType>

</GeocodePoint>

<GeocodePoint>

<Latitude>47.640144601464272</Latitude>

<Longitude>-122.12976671755314</Longitude>

<CalculationMethod>Interpolation</CalculationMethod>

<UsageType>Route</UsageType>

</GeocodePoint>

</Location>

</Resources>

</ResourceSet>

</ResourceSets>

</Response>

JSON Response

The following JSON response contains the same information as the XML response and is provided when the output (o) parameter is not set.

{

"authenticationResultCode":"ValidCredentials",

"brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",

"copyright":"Copyright © 2011 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":"Location:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",

"bbox":[

47.636257744012461,

-122.13735364288299,

47.643983179153814,

-122.12206713944467

],

"name":"1 Microsoft Way, Redmond, WA 98052",

"point":{

"type":"Point",

"coordinates":[

47.640120461583138,

-122.12971039116383

},

]

"address":{

"addressLine":"1 Microsoft Way",

"adminDistrict":"WA",

"adminDistrict2":"King Co.",

"countryRegion":"United States",

"formattedAddress":"1 Microsoft Way, Redmond, WA 98052",

"locality":"Redmond",

"postalCode":"98052"

},

"confidence":"High",

"entityType":"Address",

"geocodePoints":[

{

"type":"Point",

"coordinates":[

47.640120461583138,

-122.12971039116383

],

"calculationMethod":"InterpolationOffset",

"usageTypes":[

"Display"

 

]

},

{

 

"type":"Point",

"coordinates":[

47.640144601464272,

-122.12976671755314

],

"calculationMethod":"Interpolation",

"usageTypes":[

"Route"

]

}

],

}

]

],

"matchCodes":[

}

]

"Good"

"statusCode":200,

"statusDescription":"OK",

"traceId":"f461627364d64fd58c81b1d849ff3ec8 "

}

Find location information and request query parse information.

The following URL performs the same query as the previous example, and also requests query parse information

http://dev.virtualearth.net/REST/v1/Locations/1%20Microsoft%20Way%20Redmond%20WA%2098052?

include=queryParse&o=xml&key=BingMapsKey

This query returns the same response as above with the additional query parse information.

XML Query Parse Response

<QueryParseValue Property="AddressLine" Value="1 Microsoft Way" />

<QueryParseValue Property="Locality" Value="Redmond" />

<QueryParseValue Property="PostalCode" Value="98052" />

<QueryParseValue Property="AdminDistrict" Value="WA" />

JSON Query Parse Response

"queryParseValues":[

{

 

"property":"AddressLine",

"value":"1 Microsoft Way"

},

{

 

"property":"Locality",

"value":"Redmond"

},

{

 

"property":"PostalCode",

"value":"98052"

},

{

 

"property":"AdminDistrict",

"value":"WA"

}

]

Find location information associated with a query string and relevant to the user’s location.

The following example searches for locations associated with the search query "Kings Road". Because the userLocation parameter is specified, the results returned are relevant to the user’s location. For more information about the userLocation parameter and other user context parameters, see User Context Parameters.

http://dev.virtualearth.net/REST/v1/Locations?culture=en-

GB&query=Kings%20Road&o=xml&userLocation=51.504360719046616,-

0.12600176611298197&o=xml&key=BingMapsKey

For an example of how to use the Locations query URL with the AJAX Core Map Control, see Displaying Location Search Results Using the REST Services and the AJAX 7 Control.

Find location information associated with a query string and request neighborhood information.

The following example searches for locations associated with the search query "Greenwich, United Kingdom". Because the includeNeighborhood (inclnb) parameter is set to 1, the Neighborhood field is returned in the response.

http://dev.virtualearth.net/REST/v1/Locations/greenwich%20united%20kingdom?inclnb=1&o=xml

&key=BingMapsKey

XML Response

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">

<Copyright>

Copyright © 2011 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>

54cfe1520aa2409ab45dc489f5287c8b

</TraceId>

<ResourceSets>

<ResourceSet>

<EstimatedTotal>1</EstimatedTotal>

<Resources>

<Location>

<Name>Greenwich, London, United Kingdom</Name>

<Point>

<Latitude>51.484458923339844</Latitude>

<Longitude>0.0024300001095980406</Longitude>

</Point>

<BoundingBox>

<SouthLatitude>51.455488540347289</SouthLatitude>

<WestLongitude>-0.0595597166159628</WestLongitude>

<NorthLatitude>51.5134293063324</NorthLatitude>

<EastLongitude>0.064419716835158874</EastLongitude>

</BoundingBox>

<EntityType>Neighborhood</EntityType>

<Address>

<AdminDistrict>England</AdminDistrict>

<CountryRegion>United Kingdom</CountryRegion>

<FormattedAddress>Greenwich, London, United Kingdom</FormattedAddress>

<Locality>London</Locality>

<Neighborhood>Greenwich</Neighborhood>

</Address>

<Confidence>High</Confidence>

<MatchCode>Good</MatchCode>

<GeocodePoint>

<Latitude>51.484458923339844</Latitude>

<Longitude>0.0024300001095980406</Longitude>

<CalculationMethod>Rooftop</CalculationMethod>

<UsageType>Display</UsageType>

</GeocodePoint>

</Location>

</Resources>

</ResourceSet>

</ResourceSets>

</Response>

JSON Response

The following JSON response contains the same information as the XML response and is provided when the output (o) parameter is not set.

{

"authenticationResultCode":"ValidCredentials",

"brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",

"copyright":"Copyright © 2011 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":"Location:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",

"bbox":[

51.455488540347289,

-0.0595597166159628,

51.5134293063324,

0.064419716835158874

],

"name":"Greenwich, London, United Kingdom",

"point":{

"type":"Point",

"coordinates":[

51.484458923339844,

0.0024300001095980406

},

]

"address":{

"adminDistrict":"England",

"countryRegion":"United Kingdom",

"formattedAddress":"Greenwich, London, United Kingdom",

"locality":"London",

"neighborhood":"Greenwich"

},

"confidence":"High",

"entityType":"Neighborhood",

"geocodePoints":[

{

 

"type":"Point",

"coordinates":[

51.484458923339844,

0.0024300001095980406

],

"calculationMethod":"Rooftop",

"usageTypes":[

"Display"

]

}

],

}

]

],

"matchCodes":[

}

]

"Good"

"statusCode":200,

"statusDescription":"OK",

"traceId":"5049ac0bcbcb46198f851c516883d464"

}

Find location information for a landmark.

The following example requests location information for the Eiffel Tower.

http://dev.virtualearth.net/REST/v1/Locations/Eiffel%20Tower?o=xml&key=BingMapsKey

XML Response

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">

<Copyright>

Copyright © 2011 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>

4095ee6d5c73457495db49dacf2abc56

</TraceId>

<ResourceSets>

<ResourceSet>

<EstimatedTotal>1</EstimatedTotal>

<Resources>

<Location>

<Name>Eiffel Tower, Paris, France</Name>

<Point>

<Latitude>48.857929229736328</Latitude>

<Longitude>2.295259952545166</Longitude>

</Point>

<BoundingBox>

<SouthLatitude>48.857460021972656</SouthLatitude>

<WestLongitude>2.2933001518249512</WestLongitude>

<NorthLatitude>48.859039306640625</NorthLatitude>

<EastLongitude>2.2956900596618652</EastLongitude>

</BoundingBox>

<EntityType>Monument</EntityType>

<Address>

<AdminDistrict>IdF</AdminDistrict>

<AdminDistrict2>Paris</AdminDistrict2>

<CountryRegion>France</CountryRegion>

<FormattedAddress>Eiffel Tower, Paris, France</FormattedAddress>

<Locality>Paris</Locality>

<Landmark>Eiffel Tower</Landmark>

</Address>

<Confidence>High</Confidence>

<MatchCode>Good</MatchCode>

<GeocodePoint>

<Latitude>48.857929229736328</Latitude>

<Longitude>2.295259952545166</Longitude>

<CalculationMethod>Rooftop</CalculationMethod>

<UsageType>Display</UsageType>

</GeocodePoint>

</Location>

</Resources>

</ResourceSet>

</ResourceSets>

</Response>

JSON Response

The following JSON response contains the same information as the XML response and is provided when the output (o) parameter is not set.

{

"authenticationResultCode":"ValidCredentials",

"brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",

"copyright":"Copyright © 2011 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":"Location:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",

"bbox":[

48.857460021972656,

2.2933001518249512,

48.859039306640625,

2.2956900596618652

],

"name":"Eiffel Tower, Paris, France",

"point":{

"type":"Point",

"coordinates":[

48.857929229736328,

2.295259952545166

},

]

"address":{

"adminDistrict":"IdF",

"adminDistrict2":"Paris",

"countryRegion":"France",

"formattedAddress":"Eiffel Tower, Paris, France",

"locality":"Paris",

"landmark":"Eiffel Tower"

},

"confidence":"High",

"entityType":"Monument",

"geocodePoints":[

{

"type":"Point",

"coordinates":[

48.857929229736328,

2.295259952545166

],

"calculationMethod":"Rooftop",

"usageTypes":[

],

}

]

"Display"

"matchCodes":[

"Good"

],

}

]

}

]

"statusCode":200,

"statusDescription":"OK",

"traceId":"fb2339699bd24beab9766baf6382f926"

}

Find location information and request up to 10 location results in the response.

This example provides location information for the query string "New York" and requests up to 10 location results in the response. The default maximum number of locations returned is five (5) results.

http://dev.virtualearth.net/REST/v1/Locations?q=Greenville&maxResults=10&key=BingMapsKey

HTTP Status Codes

BingMapsKey HTTP Status Codes For more details about these HTTP status codes, see Status

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

500

503

See Also

Location Data

Location Resource

The response returned by a Locations URL contains one or more Location resources. Each Location resource contains location information that corresponds to the values provided in the request. This topic provides descriptions of the Locations resource fields, followed by JSON and XML examples.

For more information about the common response container for the Bing Maps REST Services, see Common Response Description.

JSON

XML

Type

Description

name

Name

string

The name of the resource.

point

Point

Point. For more information about the Point type, see Location and Area Types.

The latitude and longitude coordinates of the location.

bbox

BoundingBox

BoundingBox. For more information about the BoundingBox type, see Location and Area Types.

A geographic area that contains the location. A bounding box contains SouthLatitude, WestLongitude, NorthLatitude, and EastLongitude values in units of degrees.

entityType

EntityType

string

The classification of the geographic entity returned, such as Address. For a list of entity types, see Entity

JSON

XML

Type

Description

     

Types.

address

Address

Address

The postal address for the location. An address can contain AddressLine, Neighborhood, Locality, AdminDistrict,

AdminDistrict2,

CountryRegion, FormattedAddress, PostalCode, and Landmark fields. For more information about these fields, see Location and Area Types.

confidence

Confidence

One of the following values:

The level of confidence that the geocoded location result is a match. Use this value with the match code to determine for more complete information about the match.

The confidence of a geocoded location is based on many factors including the relative importance of the geocoded location and the user’s location, if specified. The following description provides more information about how confidence scores are assigned and how results are ranked.

High, Medium, Low

If the confidence is set to High, one or more strong matches were

JSON

XML

Type

Description

     

found. Multiple High confidence matches are sorted in ranked order by importance when applicable. For example, landmarks have importance but addresses do not.

If a request includes a user location or a map area (see User Context Parameters), then the ranking may change appropriately. For example, a location query for "Paris" returns "Paris, France" and "Paris, TX" both with High confidence. "Paris, France" is always ranked first due to importance unless a user location indicates that the user is in or very close to Paris, TX or the map view indicates that the user is searching in that area.

In some situations, the returned match may not be at the same level as the information provided in the request. For example, a request may specify address information and the geocode service may only be able to match a postal code. In this case, if the geocode service has a high

JSON

XML

Type

Description

     

confidence that the postal code matches the data, the confidence is set to High and the match code is set to UpHierarchy to specify that it could not match all of the information and had to search up- hierarchy.