Get Imagery Metadata
Note
Bing Maps Get Imagery Metadata API retirement
Bing Maps Get Imagery Metadata API is deprecated and will be retired. Free (Basic) account customers can continue to use Bing Maps Get Imagery Metadata API until June 30th, 2025. Enterprise account customers can continue to use Bing Maps Get Imagery Metadata API until June 30th, 2028. To avoid service disruptions, all implementations using Bing Maps Get Imagery Metadata API will need to be updated to use Azure Maps Get Map Tile API by the retirement date that applies to your Bing Maps for Enterprise account type. For detailed migration guidance, see Migrate Bing Maps Get Imagery Metadata 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 templates to get metadata for imagery that is hosted by Bing Maps. The imagery metadata returned includes URLs and dimensions for imagery tiles, ranges of zoom levels, and imagery vintage information.
Uses of this metadata include the following:
Determine the vintage of the imagery at a location.
Determine the availability of imagery at a location at a specified zoom level.
Determine the availability of different types of imagery at a location.
Build custom maps by stitching together imagery tiles.
URL Templates
Note
These templates support both HTTP and HTTPS protocols.
There are two types of imagery metadata URLs:
Complete Metadata URLs: Get imagery information that includes a map tile.
Basic Metadata URL: Get imagery information that does not include a map tile.
Complete Metadata URLs
Get the metadata for an imagery set.
Note
This template is not applicable for Birdseye imagery because Birdseye imagery requires a location.
https://dev.virtualearth.net/REST/v1/Imagery/Metadata/{imagerySet}?key={BingMapsKey}
Get the metadata for an imagery set at a specific location.
https://dev.virtualearth.net/REST/v1/Imagery/Metadata/{imagerySet}/{centerPoint}?orientation={orientation}&zoomLevel={zoomLevel}&include={ImageryProviders}&key={BingMapsKey}
Basic Metadata URL
Note
This URL returns all imagery metadata except for the map tile URL.
Get only the basic metadata for an imagery set at a specific location. This URL does not return a map tile URL.
https://dev.virtualearth.net/REST/v1/Imagery/BasicMetadata/{imagerySet}/{centerPoint}?orientation={orientation}&zoomLevel={zoomLevel}&include={ImageryProviders}&key={BingMapsKey}
Note
China currently supports the following two values for imagerySet:
- RoadOnDemand
- RoadVibrantDark
For searches in China, the meta data endpoint should like this:
https://dev.ditu.live.com/REST/V1/Imagery/Metadata/{imagerySet}?uriScheme=https&o=xml&ur=cn&c=zh-cn&key={BingMapsKey}
Template 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.
When an alias is provided, you can use the alias to shorten the length of the query parameter. For example, zoomLevel=10 can be shortened to zl=10.
Parameter values are not case-sensitive.
| Parameters | Alias | Description | Values |
|---|---|---|---|
imagerySet |
Required. The type of imagery for which you are requesting metadata. | Aerial: Aerial imagery.AerialWithLabels (Deprecated): Aerial imagery with a road overlay, using the legacy static tile service. This service is deprecated and current data will not be refreshed. New applications should instead use AerialWithLabelsOnDemand.AerialWithLabelsOnDemand: Aerial imagery with a road overlay, using the dynamic tile service.Birdseye: Bird’s eye (oblique-angle) imagery.BirdseyeWithLabels: Bird’s eye imagery with a road overlay.BirdseyeV2: The second generation Bird’s eye (oblique-angle) imagery.BirdseyeV2WithLabels: The second generation Bird’s eye (oblique-angle) imagery with a road overlay.CanvasDark: A dark version of the road maps.CanvasLight: A lighter version of the road maps which also has some of the details such as hill shading disabled.CanvasGray: A grayscale version of the road maps.OrdnanceSurvey: Ordnance Survey imagery. This imagery is visible only for the London area.Road (Deprecated): Roads without additional imagery, using the legacy static tile service. This service is deprecated and current data will not be refreshed. New applications should instead use RoadOnDemand. RoadOnDemand: Roads without additional imagery, using the dynamic tile service.Streetside: Street-level Imagery.Example: imagerySet=Aerial |
|
centerPoint |
Required when imagerySet is Birdseye, BirdseyeWithLabels, or Streetside. Optional for other imagery sets. The center point to use for the imagery metadata. | A point on the earth specified by latitude and longitude coordinates. For more information about point values, see Location and Area Types. Example: 47.610,-122.107 |
|
include |
incl |
Optional. Specifies to provide additional information about the imagery as part of the response. | The only option for this parameter is ImageryProviders. When this parameter value is specified, information about the imagery providers is returned in the response. Example: include=ImageryProviders |
orientation |
dir |
Optional. The orientation of the viewport to use for the imagery metadata. This option only applies to Birdseye imagery. | A double value between 0 to 360, where 0 = North [default], 90 = East, 180 = South, 270 = West. Example: orientation=270 |
uriScheme |
Optional. Specifies the scheme that image URL in the response should use. | Two values can be specified; http (default), https. Example: uriScheme=https |
|
zoomLevel |
zl |
Required if a centerPoint is specified and imagerySet is set to Road, Aerial or AerialWithLabels The level of zoom to use for the imagery metadata. | An integer between 1 and 21. **Note:**Some imagery may not be available at all zoom levels for all locations. If imagery is not available at a location, a message is returned in the ErrorDetails collection of the response. For more information about this collection, see Common Response Description. Example: zoomLevel=10 |
mapLayer |
ml |
Optional. A display layer that renders on top of the imagery set. | Basemap: Default, returns the regular road map with labels.Background : Only base geometry, no labels. Useful in conjunction with Foreground in cases where custom data layers need to be inserted between geometry and labels. The idea is that Foreground and Background would be requested separately and layered with the custom data in the client.Foreground: Only labels layer. Useful in conjunction with Background in cases where custom data layers need to be inserted between geometry and labels.TrafficFlow: Traffic flow layer.Buildings: Building footprints. This layer is only visible on road map imagery type.Example: mapLayer=Basemap,Buildings |
Response
When metadata for Birdseye or BirdseyeWithLabels imagery is requested, a BirdseyeMetadata resource is returned in the response. For Streetside imagery, a StreetsideMetadata resource is returned.
For other imagery types, an ImageryMetadata resource is returned. The ImageryMetadata resource may contain a map tile URL. For more information about the map tile URL and other metadata returned, see Imagery Metadata. For more information about the common response syntax for the Bing Maps REST services, see Common Response Description.
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
Get Aerial imagery metadata at street level
This example returns metadata for aerial imagery metadata at street level in New York City. Note that a center point and a zoom level are both specified. If only one of these values were specified, this URL would return an error. The response is requested in XML format.
https://dev.virtualearth.net/REST/V1/Imagery/Metadata/Aerial/40.714550167322159,-74.007124900817871?zl=15&o=xml&key={BingMapsKey}
BasicMetadata option: If you requested basic metadata only instead of the complete metadata by using the corresponding basic metadata URL template, the ImageUrl field would not be included. The rest of the response is the same.
XML Response
This example returns the following XML response. For more information about the response fields including the image URL (map tile URL), see Common Response Description and Imagery Metadata.
<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 © 2010 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>1a0d6dd60ea94171b8444a9e6e4555ca</TraceId>
<ResourceSets>
<ResourceSet>
<EstimatedTotal>1</EstimatedTotal>
<Resources>
<ImageryMetadata>
<ImageUrl>http://ecn.t3.tiles.virtualearth.net/tiles/a032010110123333.jpeg?g=471&mkt={culture}}</ImageUrl>
<ImageWidth>256</ImageWidth>
<ImageHeight>256</ImageHeight>
<ZoomMin>15</ZoomMin>
<ZoomMax>15</ZoomMax>
<VintageStart>2006-09-01</VintageStart>
<VintageEnd>2006-12-31</VintageEnd>
</ImageryMetadata>
</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 © 2010 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":"ImageryMetadata:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
"imageHeight":256,
"imageUrl":"http:\/\/ecn.t3.tiles.virtualearth.net/tiles/a032010110123333.jpeg?g=471&mkt={culture}}",
"imageUrlSubdomains":null,
"imageWidth":256,
"imageryProviders":null,
"vintageEnd":"31 Jan 2006 GMT",
"vintageStart":"01 Jan 2006 GMT",
"zoomMax":15,
"zoomMin":15
}
]
}
],
"statusCode":200,
"statusDescription":"OK",
"traceId":"dfd1a6a2c33f414abf9f41d84ed02404"
}
Get Road imagery metadata
This example gets metadata for road imagery. The response is requested in XML format.
https://dev.virtualearth.net/REST/V1/Imagery/Metadata/Road?output=xml&key={BingMapsKey}
BasicMetadata option: If you requested basic metadata only instead of the complete metadata by using the corresponding basic metadata URL template, the ImageUrl field would not be included. The rest of the response is the same.
XML Response
This example returns the following XML response. For more information about the response and resource fields including the image URL (map tile URL), see Common Response Description and Imagery Metadata.
<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 © 2010 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>648b2fb028574e159a999015b3a83b87</TraceId>
<ResourceSets>
<ResourceSet>
<EstimatedTotal>1</EstimatedTotal>
<Resources>
<ImageryMetadata>
<ImageUrl>http://ecn.{subdomain}.tiles.virtualearth.net/tiles/r{quadkey}.jpeg?g=129&mkt={culture}&shading=hill&stl=H</ImageUrl>
<ImageUrlSubdomains>
<string>t0</string>
<string>t1</string>
<string>t2</string>
<string>t3</string>
</ImageUrlSubdomains>
<ImageWidth>256</ImageWidth>
<ImageHeight>256</ImageHeight>
<ZoomMin>1</ZoomMin>
<ZoomMax>21</ZoomMax>
</ImageryMetadata>
</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 © 2010 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":"ImageryMetadata:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
"imageHeight":256,
"imageUrl":"http:\/\/ecn.{subdomain}.tiles.virtualearth.net/tiles/r{quadkey}.jpeg?g=129&mkt={culture}&shading=hill&stl=H"
"imageUrlSubdomains":[
"t0",
"t1",
"t2",
"t3"
],
"imageWidth":256,
"imageryProviders":null,
"vintageEnd":null,
"vintageStart":null,
"zoomMax":19,
"zoomMin":1
}
]
}
],
"statusCode":200,
"statusDescription":"OK",
"traceId":"d709a168fde44fe496dcbfafd829185d"
}
Get Birdseye imagery metadata
This example gets metadata for Birdseye imagery of San Francisco. The response is requested in XML format.
https://dev.virtualearth.net/REST/V1/Imagery/Metadata/Birdseye/37.779160067439079,-122.42004945874214?o=xml&key={BingMapsKey}
BasicMetadata option: If you requested basic metadata only instead of the complete metadata by using the corresponding basic metadata URL template, the ImageUrl field would not be included. The rest of the response is the same.
XML Response
This example returns the following XML response. For more information about the response fields including the image URL (map tile URL), see Common Response Description and Imagery Metadata.
<Response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">
<Copyright>Copyright © 2017 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>776700d9a33e4712b308697da7619c9f|CO30276302|7.7.0.0|</TraceId>
<ResourceSets>
<ResourceSet>
<EstimatedTotal>1</EstimatedTotal>
<Resources>
<BirdseyeMetadata>
<ImageUrl>http://ak.{subdomain}.tiles.virtualearth.net/tiles/be000122033113001-9-14-{zoom}-{tileId}.jpeg?g=5777&key={BingMapsKey}</ImageUrl>
<ImageUrlSubdomains>
<string>t0</string>
<string>t1</string>
<string>t2</string>
<string>t3</string>
</ImageUrlSubdomains>
<ImageWidth>512</ImageWidth>
<ImageHeight>512</ImageHeight>
<ZoomMin>18</ZoomMin>
<ZoomMax>21</ZoomMax>
<VintageStart>2013-10-17</VintageStart>
<VintageEnd>2013-10-17</VintageEnd>
<Orientation>0</Orientation>
<TilesX>9</TilesX>
<TilesY>14</TilesY>
</BirdseyeMetadata>
</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 © 2017 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": "BirdseyeMetadata:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
"imageHeight": 512,
"imageUrl": "http:\/\/ak.{subdomain}.tiles.virtualearth.net\/tiles\/be000122033113001-9-14-{zoom}-{tileId}.jpeg?g=5777&key={BingMapsKey}",
"imageUrlSubdomains": ["t0", "t1", "t2", "t3"],
"imageWidth": 512,
"imageryProviders": null,
"vintageEnd": "17 Oct 2013 GMT",
"vintageStart": "17 Oct 2013 GMT",
"zoomMax": 21,
"zoomMin": 18,
"orientation": 0,
"tilesX": 9,
"tilesY": 14
}]
}],
"statusCode": 200,
"statusDescription": "OK",
"traceId": "1ddf6f4da2f34ee480cf5c1958776a24|CO30275838|7.7.0.0|"
}
Get Road imagery metadata and imagery provider information
This example returns road imagery metadata and requests information about the imagery providers. The response is returned in JSON format. You can specify to return the response in XML format by setting the output parameter to xml.
https://dev.virtualearth.net/REST/v1/Imagery/Metadata/Road?incl=ImageryProviders&key={BingMapAPIKey}
Get Birdseye imagery metadata centered at a point
This example returns Birdseye imagery metadata for imagery that is centered at the specified point. The response is returned in JSON format. You can specify to return the response in XML format by setting the output parameter to xml.
https://dev.virtualearth.net/REST/v1/Imagery/Metadata/Birdseye/47.23,-122.3?key={BingMapsKey}
Get BirdseyeWithLabels imagery metadata centered at a point and from a viewport angle of 90 degrees
The example gets Birdseye imagery metadata for imagery that includes labels and that has an orientation angle of 90 degrees. The imagery is centered at the specified point. The response is returned in JSON format. You can specify to return the response in XML format by setting the output parameter to xml.
https://dev.virtualearth.net/REST/v1/Imagery/Metadata/BirdseyeWithLabels/47.23,-122.3?dir=90&key={BingMapsKey}
Get Road imagery metadata centered at a point and for a specified zoom level
This example returns road imagery metadata that is centered at the specified point with a zoom level of 10. . The response is returned in JSON format. You can specify to return the response in XML format by setting the output parameter to xml.
https://dev.virtualearth.net/REST/v1/Imagery/Metadata/Road/47.23,-122.3?zl=10&key={BingMapsKey}
Get Aerial imagery metadata centered at a point and for a specified zoom level
This example returns metadata for aerial imagery that is centered at the specified point with a zoom level of 10. The response is returned in JSON format. You can specify to return the response in XML format by setting the output parameter to xml.
https://dev.virtualearth.net/REST/v1/Imagery/Metadata/Aerial/47.23,-122.3?zl=10&key={BingMapsKey}
Get AerialWithLabels metadata centered at a point and for a specified zoom level
This example returns metadata for aerial imagery with labels and that is centered at the specified point with a zoom level of 10. The response is returned in JSON format. You can specify to return the response in XML format by setting the output parameter to xml.
https://dev.virtualearth.net/REST/v1/Imagery/Metadata/AerialWithLabels/47.23,-122.3?zl=10&key={BingMapsKey}
Get Streetside metadata centered at a point
This example returns metadata for Streetside imagery at a point in Ballard, Seattle.
The URL request:
http://dev.virtualearth.net/REST/v1/Imagery/MetaData/Streetside/47.668687,-122.384795?key={BingMapsKey}
The JSON response:
{
"authenticationResultCode": "ValidCredentials",
"brandLogoUri": "http://dev.virtualearth.net/Branding/logo_powered_by.png",
"copyright": "Copyright © 2018 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": "StreetsideMetadata:http://schemas.microsoft.com/search/local/ws/rest/v1",
"imageHeight": 256,
"imageUrl": "http://ecn.{subdomain}.tiles.virtualearth.net/tiles/hs0203232101212100{faceId}{tileId}?g={BingMapsAPIKey}",
"imageUrlSubdomains": [
"t0",
"t1",
"t2",
"t3"
],
"imageWidth": 256,
"imageryProviders": null,
"vintageEnd": "17 Jul 2014 GMT",
"vintageStart": "17 Jul 2014 GMT",
"zoomMax": 4,
"zoomMin": 1,
"he": 52.286,
"lat": 47.668696,
"lon": -122.384813,
"pi": 0.638,
"ro": -0.326
}
]
}
],
"statusCode": 200,
"statusDescription": "OK",
"traceId": "3f6f6409f04d4e4b93dcdd50fee6b508|CO3124D6DA|7.7.0.0"
}
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