Find a Location by Address

Article
07/20/2022

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

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/region by setting one or more of the parameters in the following URL.

http://dev.virtualearth.net/REST/v1/Locations?countryRegion={countryRegion}&adminDistrict={adminDistrict}&locality={locality}&postalCode={postalCode}&addressLine={addressLine}&userLocation={userLocation}&userIp={userIp}&usermapView={usermapView}&includeNeighborhood={includeNeighborhood}&maxResults={maxResults}&key={BingMapsKey}

Get the latitude and longitude coordinates based on a set of address values for specific countries/regions**

Note

You can substitute a hyphen (-) for any structured URL parameter when there is no value.

For countries/regions 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/region as part of the URL path.

Canada

http://dev.virtualearth.net/REST/v1/Locations/CA/{adminDistrict}/{postalCode}/{locality}/{addressLine}?includeNeighborhood={includeNeighborhood}&include={includeValue}&maxResults={maxResults}&key={BingMapsKey}

France

http://dev.virtualearth.net/REST/v1/Locations/FR/{postalCode}/{locality}/{addressLine}?includeNeighborhood={includeNeighborhood}&include={includeValue}&maxResults={maxResults}&key={BingMapsKey}

Germany

http://dev.virtualearth.net/REST/v1/Locations/DE/{postalCode}/{locality}/{addressLine}?includeNeighborhood={includeNeighborhood}&include={includeValue}&maxResults={maxResults}&key={BingMapsKey}

United Kingdom

http://dev.virtualearth.net/REST/v1/Locations/UK/{postalCode}?includeNeighborhood={includeNeighborhood}&include={includeValue}&maxResults={maxResults}&key={BingMapsKey}

United States

http://dev.virtualearth.net/REST/v1/Locations/US/{adminDistrict}/{postalCode}/{locality}/{addressLine}?includeNeighborhood={includeNeighborhood}&include={includeValue}&maxResults={maxResults}&key={BingMapsKey}

http://dev.virtualearth.net/REST/v1/Locations/US/{adminDistrict}/{locality}/{addressLine}?includeNeighborhood={includeNeighborhood}&include={includeValue}&maxResults={maxResults}&key={BingMapsKey}

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={BingMapsKey}

Find a Location by Query query: http://dev.virtualearth.net/REST/v1/Locations?q=100%20Main%20St.%20Somewhere,%20WA%2098001&key={BingMapsKey}

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/region.	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`
`strictMatch`	`sm`	Optional. Restricts the geocode result to the country or region that is specified in the countryRegion field and the state, province or territory specified in the adminDistrict field.	One of the following values: - `1`: Restrict results to the specified countryRegion and adminDistrict. - `0` [default]: Do not restrict results to the specified countryRegion and adminDistrict. Example: `strictMatch=1`

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=xml&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=xml&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={BingMapsKey}

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%20Causeway?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?key={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%205?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={BingMapsKey}

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

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

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.

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

Find a Location by Address

URL Templates

Get the latitude and longitude coordinates based on a set of address values for any country/region

API Parameters

Response

Examples

Find location information for a United States street address including the ZIP Code

Find location information for a United States street address without a postal code

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

Find location information by using a structured URL where some parameters have no value

Find location information by using an unstructured URL and setting the userLocation parameter

Find location information and request neighborhood information in the response

Find location information for Canada

Find location information for France

Find location information for Germany

Find location information for the United Kingdom

Find location information by using an unstructured URL

HTTP Status Codes

See Also

Additional resources