Find a Location by Point

Artículo
05/21/2024

Note

Bing Maps Find a Location by Point API retirement

Bing Maps Find a Location by Point API is deprecated and will be retired. Free (Basic) account customers can continue to use Bing Maps Find a Location by Point API until June 30th, 2025. Enterprise account customers can continue to use Bing Maps Find a Location by Point API until June 30th, 2028. To avoid service disruptions, all implementations using Bing Maps Find a Location by Point API will need to be updated to use Azure Maps Get Reverse Geocoding API by the retirement date that applies to your Bing Maps for Enterprise account type. For detailed migration guidance, see Migrate Bing Maps Find a Location by Point API.

Azure Maps is Microsoft's next-generation maps and geospatial services for developers. Azure Maps has many of the same features as Bing Maps for Enterprise, and more. To get started with Azure Maps, create a free Azure subscription and an Azure Maps account. For more information about azure Maps, see Azure Maps Documentation. For migration guidance, see Bing Maps Migration Overview.

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:

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

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

Compartir a través de

Find a Location by Point

URL Template

API Parameters

Response

Examples

Find location information for a specified point on the Earth

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

HTTP Status Codes

See Also

Recursos adicionales