Find a Location by Point

  • Article

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

Note

These templates support both HTTP and HTTPS protocols. To use this API, you must have a Bing Maps Key.

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

http://dev.virtualearth.net/REST/v1/Locations/{point}?includeEntityTypes={entityTypes}&includeNeighborhood={includeNeighborhood}&include={includeValue}&key={BingMapsKey}

API Parameters

Note

See the Common Parameters and Types section for additional common parameters to use with these URLs.

Common parameters include:

Parameter values are not case-sensitive.

Parameters Alias Description Values
includeEntityTypes Optional. 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 entity types you specify, no location information is returned in the response. A comma separated list of entity types selected from the following options.

- Address
- Neighborhood
- PopulatedPlace
- Postcode1
- AdminDivision1
- AdminDivision2
- 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 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 when it is available. 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
verboseplacenames vbpn Optional. Either true or false

- If false: "AdminDistrict" names will be in the officially abbreviated form (e.g.: “WA” for Washington state in USA).

-If true: "AdminDistrict" names will be in expanded form (e.g.: "Washington" instead of "WA" in the USA).		 Default value is false.

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.

Note

The Location by Point API returns an additional intersection field in the address resource for all successful responses.

Intersection Resource

JSON XML Description
baseStreet BaseStreet Primary street for the location.
secondaryStreet1 SecondaryStreet1 The first intersecting street.
secondaryStreet2 SecondaryStreet2 If any, the second intersecting street.
intersectionType IntersectionType Type of intersection.
displayName DisplayName Complete name of the intersection.

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

Note

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

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

  • 200

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

  • 400
  • 401
  • 404
  • 429
  • 500
  • 503

See Also

Using the REST Services with .NET
JSON Data Contracts
Geocoding a Location Getting Route Directions
Find a location by query