none
New URL Templates for Bing Maps Tiles

    General discussion

  • As part of our ongoing efforts to improve performance and functionality of the Bing Maps Platform we are moving the delivery of Bing Maps tiles to an on-demand process which gives us a greater flexibility, enables us to shorten the refresh-cycles and will allow us further down the line among other things a more comprehensive localization of map labels.

    Unfortunately along with these improvements comes the need to change the URL templates for tile requests. These changes will be implemented over the next 24 hours and are seamless, if you use one of our map controls. However, if you access our tiles directly or use a 3<sup>rd</sup> party control that does so, your application could be impacted.

    Does your application require a code change?

    Your application does not require a code change, if

    1. You use one of the Bing Maps controls (AJAX, Windows Store, WPF, Silverlight, Windows Phone, iOS)
    2. You built your own map control and determine the URL-template using the SOAP Imagery service before you retrieve the tiles via http. This approach will also work for https if you use the optional parameter UriScheme in the ImageryMetadataOptions.
    3. You built your own map control and determine the URL-template using the REST Imagery service before you retrieve the tiles only via http.
    4. You use a 3<sup>rd</sup> party control that implements the tiles-requests as mentioned in 2 or 3.

    Your application will require a code change, if:

    1. You built your own map control and have hard-coded parts of the URL template for the tile request.
    2. You built your own map control and use the REST Imagery service to generate the tile-request but also support the https endpoints.
    3. You built your own map control and use the SOAP Imagery service to generate the tile-request but also support https-endpoints and do not use the optional parameter Uri Scheme.

    What is changing?

    If you currently use the REST Imagery service to determine the URL template for tile-requests you execute a request like

    http://dev.virtualearth.net/REST/v1/Imagery/Metadata/Road?key=YOUR_BING_MAPS_KEY

    Today the response will look like the below JSON-object.

    {
    	"authenticationResultCode":"ValidCredentials",
    	"brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",
    	"copyright":"Copyright © 2013 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 Corpora-tion.",
    	"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=1515&mkt={culture}&shading=hill",
    			"imageUrlSubdomains":["t0","t1","t2","t3"],
    			"imageWidth":256,
    			"imageryProviders":null,
    			"vintageEnd":null,
    			"vintageStart":null,
    			"zoomMax":21,
    			"zoomMin":1
    		}]
    	}],
    	"statusCode":200,
    	"statusDescription":"OK",
    	"traceId":"2b92bc58b25145a3bac1122061bf4188|BAYM000013|02.00.172.1500|"
    }

    The new URL-template for http-endpoints will look like:

    {
    	"authenticationResultCode":"ValidCredentials",
    	"brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",
    	"copyright":"Copyright © 2013 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 Corpora-tion.",
    	"resourceSets":[
    	{
    		"estimatedTotal":1,
    		"resources":[
    		{
    			"__type":"ImageryMetadata:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
    			"imageHeight":256,
    			"im-ageUrl":"http:\/\/ak.dynamic.{subdomain}.tiles.virtualearth.net\/comp\/ch\/{quadkey}?mkt={culture}&it=G,L&shading=hill&og=23&n=z",
    			"imageUrlSubdomains":["t0","t1","t2","t3"],
    			"imageWidth":256,
    			"imageryProviders":null,
    			"vintageEnd":null,
    			"vintageStart":null,
    			"zoomMax":21,
    			"zoomMin":1
    		}]
    	}],
    	"statusCode":200,
    	"statusDescription":"OK",
    	"traceId":"be8d8bc69a4940e1aa4d403e4ec624fb|CO30275938|02.00.172.2900|"
    }
    Before the URL-template for http- and https-endpoints was the same and you only needed to replace the protocol in the tile-request. With the upcoming changes this is not so anymore and the URL-template is indeed different. For https-endpoints the request should now include a parameter uriScheme, e.g. 
    https://dev.virtualearth.net/REST/v1/Imagery/Metadata/Road?uriScheme=https&key=YOUR_BING_MAPS_KEY
    and the response in JSON-format will be:
    {
    	"authenticationResultCode":"ValidCredentials",
    	"brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",
    	"copyright":"Copyright © 2013 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 Corpora-tion.",
    	"resourceSets":[
    	{
    		"estimatedTotal":1,
    		"resources":[
    		{
    			"__type":"ImageryMetadata:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
    			"imageHeight":256,
                        "imageUrl":"https:\/\/{subdomain}.ssl.ak.dynamic.tiles.virtualearth.net\/comp\/ch\/{quadkey}?mkt={culture}&it=G,L&shading=hill&og=23&n=z",
    			"imageUrlSubdomains":["t0","t1","t2","t3"],
    			"imageWidth":256,
    			"imageryProviders":null,
    			"vintageEnd":null,
    			"vintageStart":null,
    			"zoomMax":21,"zoomMin":1
    		}]
    	}],
    	"statusCode":200,
    	"statusDescription":"OK",
    	"traceId":"86eabdc0d1ec4dca8281fca3c9b48668|CO30276241|02.00.172.2900|"
    }

    http://rbrundritt.wordpress.com

    Tuesday, January 21, 2014 10:11 AM
    Owner

All replies

  • So "imageUrl" is changing to "im-ageUrl"?
    Tuesday, January 21, 2014 7:05 PM
  • Was this announced anytime earlier than 5a ET on the day it was to go into effect?
    Tuesday, January 21, 2014 7:37 PM
  • API breaking changes with 24 hours notice!  Really!!?

    P.S.  HTML works best when you don't escape the tags.

    3<sup>rd</sup>

    Tuesday, January 21, 2014 7:40 PM
  • Ricky, are the "it" options for the dynamic tiles documented somewhere?

    eg, we used to be able to get the road data and labels on a transparent background, really useful for putting our content under, using:

    http://ecn.t{subdomain}.tiles.virtualearth.net/tiles/ho{quadkey}.png?g=673&mkt=en-US&n=z&stl=h'

    I havn't been able to fins this in the new scheme.

    John.

    Tuesday, January 21, 2014 10:15 PM
  • Can't believe that a breaking change was released without any notification to users or even adequate documentation.  I expect much better than this from a company like Microsoft.
    Tuesday, January 21, 2014 10:54 PM
  • I noticed that the REST imagery service returns the old information again. Will this remain this way or will Microsoft change the URLs again without informing their customers?

    Please, Microsoft, give us information about what you are going to change and when you wiil do it.


    Thomas Sadleder

    Wednesday, January 22, 2014 8:06 AM
  • This release was rolled back. This release was not meant to be a breaking release. This release was meant to be of a new, non-existing feature. It's unusual to announce these types of releases. It just happened that some new data centers were brought online at the same time as this release which did not have the proper certificates. This caused the certificate error. The change to the imagery service was meant to add a new feature which returned the HTTPS tile URL in the imagery metadata response for the new dynamic tiles. Note that the imagery metadata service did not return https tile url's before. Unfortunately a large number of 3rd party map controls which use the Bing Maps tiles used a work around to access the tiles using https. This work around broke and accounted for most of the reported issues. Most of these reports came from users of OpenLayers.

    As for the uriSchema parameter, if you look at the new tile url's you will see that it is a new dynamic tile service. This uriSchema parameter is needed for this dynamic tile service to work properly.

    This release will likely be made in the future. No details to share at the moment. The feature that was meant to be released is an important one as it not only adds support for https but also a number of other things related to the tiles which I can't announce at this time.

    As for the comments about my original post and html formatting. I actually just copied and pasted this from the original announcement made by someone else so that this would be easier to find. You can find the original announcement here: http://social.msdn.microsoft.com/Forums/en-US/home?forum=bingmapsservices&announcementId=1e0a8543-8328-4fa8-a037-d27b908583db


    http://rbrundritt.wordpress.com

    Wednesday, January 22, 2014 10:21 AM
    Owner
  • Rick, that sounds good but it would be awesome if, in the absence of an explicit uriSchema parameter, MS would infer the schema by choice of endpoints

    http://dev.virtualearth.net/REST/v1/Imagery/Metadata/Road/0,0?zoomLevel=1&key={0}

    or

    https://dev.virtualearth.net/REST/v1/Imagery/Metadata/Road/0,0?zoomLevel=1&key={0}

    Also, can I get notified in the future- perhaps simply by your posting on this thread again- when the change is again scheduled?

    Thanks,

         Russell


    Russell

    Wednesday, January 22, 2014 1:49 PM
  • I agree it would be nice if we didn't have to have the uriSchema parameter but I'm not on the development team and don't have too much insight into why that needs to be done. As for announcing the next/future releases. This has to be done by our product group. They choose not to announce this release. It has been stressed the importance of announcing future releases. However I'd get in trouble if I announce a release before it happens without permission.

    http://rbrundritt.wordpress.com

    Wednesday, January 22, 2014 2:27 PM
    Owner
  • Thanks for the quick response.  Can you at least kick the suggestion about inferring endpoints up to them?  Because if they can do that, I and likely others will not need to recode for this change.

    Russell

    Wednesday, January 22, 2014 2:57 PM
  • Ah, I see the announcement now.

    Wow, that is a really poor way to make an announcement.  It seems the only way to know there's a new announcement is to notice that the "3 announcements" and changed to "4 announcements!"  I hope future announcements also get a discussion topic added - preferably several months before a breaking change.

    Thanks to Ricky for realizing that just about no-one is going to see this announcement and reposting it!

    Wednesday, January 22, 2014 6:19 PM
  • So this has been rolled back... and yet the announcement is still up?

    This is getting really worrisome.

    Thursday, January 23, 2014 5:53 PM
  • I've left the announcement up in case people are still having issues. Everything was rolled back and most customers have confirmed everything is back to normal.

    http://rbrundritt.wordpress.com

    Friday, January 24, 2014 8:52 AM
    Owner
  • I'm worried about obtaining the transparent label tiles as well.

    I'm displaying weather data(radar,satellite,etc.) and it's useless if city names and roads are obscured underneath the data layer

    Wednesday, February 12, 2014 9:47 PM
  • Thursday, February 13, 2014 11:36 AM
    Owner