Please note that you can safely ignore the following migration hints when using the Bing Maps Aerial layer with a privately obtained key. Existing software will continue to work.
If you are using Bing Maps Aerial tiles in your applications, either through PTV components or by directly accessing the Bing Maps services, it will be necessary to migrate to HERE Satellite when you are currently accessing Bing Maps with a key provided by PTV. PTV's keys are set to expire on April 1st, 2014 and the entire imagery service will be provided by HERE Satellite after April 1st.
Switching to HERE Satellite implies changes in your application even when consuming the satellite imagery through PTV components. The following sections will help you to migrate from Bing Maps Aerial to HERE Satellite, describing the migration in these scenarios:
| Customer Integration Testing (CIT) | http://{subdomain}.aerial.maps.cit.api.here.com... |
|---|---|
| Productive Environment | http://{subdomain}.aerial.maps.api.here.com... |
In the migration sections below we solely refer to the CIT environment. Please note that the URLs must be changed once your application becomes productive. The following sections provide additional information on both environments.
Given that the production environment is a live system and common to all API users, we request that you use the alternative Customer Integration Testing (CIT) environment when evaluating our products, running tests, making changes in your code and altering the way you access our APIs. The CIT environment also allows you to test your software against a newer version of the service before HERE brings that version into production. CIT offers a fully functional environment for customers to use for development and testing, but it does not support high loads or performance testing in general.
The CIT environment is intended for integration testing only. Commercial or productive use is not allowed.
The servers that process requests against the API resources are distributed for optimized load balancing. Clients can take advantage of this and improve response times, especially when submitting multiple simultaneous requests.
This URL is to be used in production environment according to your given licenses.
Please note that both URL and access keys can change, e.g. to reflect API changes (URL) or for security reasons (keys). If the HERE Satellite URL changes, the service will usually be accessible for six months using the previously valid URL. In general, we recommend to keep URL and keys configurable instead of coding them into your application.
Summary: Omit the meta data request and use the fixed HERE Satellite request template in your layer / map control implementation.
When you are directly accessing Bing Maps Aerial Layer in your application, your code usually works this way:
http://dev.virtualearth.net/REST/V1/Imagery/Metadata/Aerial?o=xml&key=<Bing-Maps-Key>for meta data. Usually you will do this only once, when the application starts or when the layer is activated for the first time.
http://ecn.{subdomain}.tiles.virtualearth.net/tiles/a{quadkey}.jpeg?g=2271With HERE Satellite, a meta data request is no longer necessary. Instead, you'll directly work with the HERE Satellite request template that looks like this:
http://{subdomain}.aerial.maps.cit.api.here.com/maptile/2.1/maptile/newest/satellite.day/{z}/{x}/{y}/256/png8?app_id={app_id}&app_code={app_code}Please note that the URL above refers to the CIT environment and should be used for test purposes only.
Filling in the following placeholders you should be able to feed your layer (or map control, respectively) with satellite tiles:
| {subdomain} | 1, 2, 3 or 4 |
| {x}, {y}, {z} | Tile coordinate ("Google tiling scheme"). You do not need to transform the tile coordinate into a quadkey as with Bing Maps. |
| {app_id}, {app_code} | Your access keys. |
Summary: With an updated version of PTV Ajax Maps in place, use map.addTiledAerialLayer along with
the HERE Satellite url instead of map.addBingAerialLayer.
In PTV Ajax maps, the migration from Bing Maps to HERE Satellite reduces to a few lines of code,
provided that at least PTV Ajax Maps 3.0.4 is in use. Instead of
using map.addBingAerialLayer, you need to call map.addTiledAerialLayer,
passing in the HERE Satellite url template:
...
// Google tiling is required for tile sources
com.ptvag.webcomponent.map.CoordUtil.useGoogleZoomLevels();
...
// create the map
var map = new com.ptvag.webcomponent.map.Map(document.getElementById("mapContainer"));
...
var appId = '<your app_id>', appCode = '<your app_code>';
// HERE Satellite request template
var template = 'http://{subdomain}.aerial.maps.cit.api.here.com/maptile/2.1/maptile' +
'/newest/satellite.day/{z}/{x}/{y}/256/png8?app_id=' + appId + '&app_code=' + appCode;
// Adds the HERE Satellite layer to the map and wires it up with the toolbar buttons for switching views.
map.addTiledAerialLayer('HERE-Satellite', template, ['1', '2', '3', '4']);
...Please note that the URL above refers to the CIT environment and should be used for test
purposes only. Please do also note that there's no callback parameter in addTiledAerialLayer, as
addTiledHereAerialLayer works synchronous without additional initialization requests being sent.
Summary: Replace your Bing Map configuration in wms.properties with HERE Satellite configuration. It
might additionally be necessary to adopt the naming in your application.
When you are proxying Bing Maps through the PTV WMS Servlet, there is a Bing Maps Arial configuration in
your wms.properties configuration file (located in the <xmap>/conf folder)
that needs to be replaced with a HERE Satellite configuration.
With an updated version of the PTV WMS Servlet in place, configuring HERE Satellite is as
simple as adding the following lines to your configuration file, replacing the {app_id} and {app_code}
placeholders with your keys:
...
#
# configuration of the known layers
#
layers=...,here-satellite
...
here-satellite.type=com.ptvag.wms.layer.TileLayer
here-satellite.description=HERE Satellite
here-satellite.urlTemplate=http://{subdomain}.aerial.maps.cit.api.here.com/maptile/2.1/maptile/newest/satellite.day/{z}/{x}/{y}/256/png8?app_id={app_id}&app_code={app_code}
here-satellite.subDomains=1,2,3,4
...Please note that the URL above refers to the CIT environment and should be used for test purposes only.
When removing the Bing Maps Aerial configuration from wms.properties, please be sure to remove the layer
from the layers key that lists all available layers also. Otherwise the PTV WMS Servlet may not start correctly.
As written above, integrating HERE Satellite through com.ptvag.wms.layer.TileLayer requires an updated servlet
that is not yet included in PTV xMap Server but probably will be in one of the next releases.
If you were using Bing Maps Aerial through PTV xMap Server previously (deprecated), it is also possible to adopt configuration to reflect the changes of the PTV WMS Servlet and to render HERE Satellite tiles. In order to do that you need to overwrite xMap Server's Bing Maps template:
...
bingMaps.template=http://127.0.0.1:50010/WMS/WMS?REQUEST=GetMap&width={width}&height={height}&bbox={minx},{miny},{maxx},{maxy}&format=image/png&version=1.1.1&layers=here-satellite&srs=EPSG:505456
...The template can be configured e.g. in PTV xMap Server's default profile, xmap-default.properties. You need
to adopt the url if the layer is not named here-satellite in your WMS configuration. Please note that the
aerial layer in PTV xMap Server still has to be requested using the layername "bingmaps" no matter what name
has been used in the WMS configuration.
Summary: Replace your Remote Image Layer's configuration of Bing Maps taking the OSM demo layer as template for creating a tiled layer based on the fixed HERE Satellite request template.
When you've configured the Bing Maps Aerial layer in Mapserver's Remote Image Layer configuration file (eMSLay.ini), you need to replace this layer with one using the HERE Satellite url template as a tile source.
The best way to do this is to start with the default eMSLay.ini configuration file that is shipped with the SDK setup. Please refer to Mapserver's documentation when you are unsure about the location and usage of this configuration file.
The default eMSLay.ini configures OSM as a tile source in the section [TileLayerDemo], and this section
is also a valid configuration template for HERE Satellite. A minimal HERE Satellite configuration may look like this:
// The following section configures the HERE Satellite layer.
[HereSatellite]
// visibility on startup. Defaults to 1, visible.
Visible=0
// visible layer name. Defaults to the section name of this ini-file
// section, if not set ("TileLayerDemo" in this case)
VisibleName=HERE Satellite
// HERE Satellite url template
Url=tile://%SUBDOMAIN%.aerial.maps.cit.api.here.com/maptile/2.1/maptile/newest/satellite.day/%TZ%/%TX%/%TY%/256/png8?app_id={app_id}&app_code={app_code}
// comma-separated subdomains
Url.Subdomains=1,2,3,4Please note that the URL above refers to the CIT environment and should be used for test
purposes only. Be sure not not mistake {app_id} and {app_code} for Remote Image
Layer parameters. These two placeholders are to be replaced within eMSLay.ini with your access keys. Change or add
other settings (name, visibility, proxy etc.) as needed.
When starting your Mapserver based application, the HERE Satellite layer will be inserted automatically in the map as was
the Bing Maps layer before. The layer may or may not be visible though, depending on your configuration of the Visible
parameter.
Summary: Replace your call to map.AddBingLayer with a few lines of code inserting a tiled layer into the
map that accesses the HERE Satellite tiles.
When using PTV xServer .NET, you need to replace the call to map.AddBingLayer, that previously initialized
and added the Bing Maps Aerial layer to the map. Unfortunately, there is no single line replacement for map.AddBingLayer.
However, PTV xServer .NET offers configurable tile layers and tile sources out of the box so that the HERE Satellite layer
can be integrated with a few lines of code:
...
// HERE Satellite request template with placeholders for subdomain, x, y, and z (in that order)
const string hereSatelliteUrl = "http://{0}.aerial.maps.cit.api.here.com/maptile/2.1/maptile/newest/satellite.day/{3}/{1}/{2}/256/png8?app_id={app_id}&app_code={app_code}";
// insert on top of xServer background
int idx = map.Layers.IndexOf(map.Layers["Background"]) + 1;
// create HERE Satellite layer
var hereSatelliteLayer = new Ptv.XServer.Controls.Map.Layers.Tiled.TiledLayer("HERE Satellite")
{
TiledProvider = new Ptv.XServer.Controls.Map.TileProviders.RemoteTiledProvider()
{
MinZoom = 0,
MaxZoom = 19,
RequestBuilderDelegate = (x, y, z) => String.Format(hereSatelliteUrl, (x + y) % 4 + 1, x, y, z)
},
IsBaseMapLayer = true,
Opacity = 0.8,
Copyright = "© HERE",
Icon = ResourceHelper.LoadBitmapFromResource("Ptv.XServer.Controls.Map;component/Resources/Aerials.png")
};
// insert layer
map.Layers.Insert(idx, hereSatelliteLayer);
...Please note that the URL above refers to the CIT environment and should be used for test
purposes only. Be sure to replace {app_id} and {app_code} in the url template, when
copying the code snippet above into your application. All other placeholders will be replaced automatically by
the RequestBuilderDelegate that is triggered when aerial tiles are to be rendered.