[ Whereis® API Home ] [ Developers' Guide ]
Whereis API v2 is not backward compatible with v1. This is an overview of the changes you will need to make to upgrade to v2. To familiarise yourself with v2, you may also wish top read the Developers’ Guide.
Conformity to mapping standard practice
Several changes have been made to make the WhereIs API more compatible with other mapping APIs
- Map tiles are now 256 x 256, instead of 400 x 400 or 200 x 200
- The map projection is changed to Spherical Mercator (previously Ellipsoidal Mercator)
- XYZ of map tiles is now consistent with most other mapping APIs
- Map zoom levels have been changed. Please refer to Appendix 3 - Zoom Levels
API Import changes
Changes have been made to simplify the amount of HTML code required to get started. The example below shows the changes required:
<!-- remove old DOCTYPE and replace with HTML 5 doctype -->
<!DOCTYPE html>
<head>
...
<!-- REMOVE ALL Whereis-related javascript includes, CSS links and crossDomain settings.
Remove unnecessary IE compatibility meta tag
<meta http-equiv="X-UA-Compatible" content="IE=7" />
<script type="text/javascript" src="<old_path>/js/ol/OpenLayers.js"></script>
<script type="text/javascript" src="<old_path>/js/ems/EMS.js?token=<token>"></script>
<link rel="stylesheet" href="<old_path>/js/ol/theme/default/style.css" type="text/css" />
<link rel="stylesheet" href="<old_path>/js/ems/theme/default/style.css" type="text/css" />
<script type="text/javascript">EMS.Services.communicationMode = "CrossDomain";</script>
-->
<!-- ADD NEW EMS INCLUDE -->
<script type="text/javascript" src="http://api.ems.sensis.com.au/v2/web/js/ems/?token=<token>">
</script>
..
</head>
This table shows all the changes to how you import the Whereis API:
| Component | Change | Reference |
|---|---|---|
| URLs | Version 2 uses a different URL to v1 | The Whereis® API |
| Token | No change. Your existing v1 token will continue to work with v2. | |
| Script include | Version 2 uses a single JavaScript include which generates all required imports. This means you no longer need to have separate JavaScript includes for EMS and OpenLayers, or CSS stylesheet links. | |
| Cross domain mode | Cross domain mode is now the default communication mode so you are no longer required to explicitly set it. | |
| 3rd Party Frameworks | Version 2 manages all OpenLayers dependencies for you. If you need something from OpenLayers that is not exposed by default, you can add the component you need to via the <libraries> parameter | EMS JavaScript API |
| Compression | Compression of JavaScript source is ON by default in v2. If you wish for compression to be off, then set request parameter <compress> to false, i.e &compress=false | EMS JavaScript API |
| Profiles | The <profile> parameter has been superseded by <libraries> | EMS JavaScript API |
| Development mode | In v1 the multiple file “development” version was selected by modifying your EMS path to <path>/v1/web/js/ems/lib/EMS.js. In v2, you add “/debug” to your path, e.g. <path>/web/js/ems/debug/?token=<token> |
Interface changes
Once you have changed over to v2, your code will not work. The following modifications will need to be made:
| Element | Change | Description | Reference |
|---|---|---|---|
| LonLat | EMS.LonLat.lon not equal to EMS.LonLat().asWGS84().lon | Longitude values for Ellipsoidal Mercator projection are the same as for WGS84. This meant in v1 you could return the standard WGS84 value of a longitude from the property LonLat.lon. Projection changes to Spherical Mercator now mean that you must use asWGS84() to return the standard WGS84 value for longitude as well as latitude | Location Readme |
| Map | Namespace change | Namespace for map has been simplified. EMS.Services.Map becomes EMS.Map | Map Basics |
| Map.print2() has been is removed | Instead, use EMS.Service.StaticMap(). | Static map | |
| Default layers are no longer exposed as map properties | To return a default layer, use Map.getLayerByName(<layer_name>). For example: // var layer = map.whereis_street_wms; var layer = map.getLayerByName(EMS.Layer.STREET); // v2 | Layers | |
| Add markers directly to map | In v1, markers were added or removed via functions on the markers layer. In v2 these functions are also exposed on the map object. For example: // map.markersLayer.addMarker(marker); map.addMarker(marker); //map.markersLayer.removeMarker(marker); map.removeMarker(marker); | Markers | |
| Mouse control no longer exposed as map property | in v1 the default mouse control was exposed as map.mouseDefaults. | ||
| Icons | Namespace changed | Namespace for icons has been simplified from EMS.Services.StandardIcons to EMS.Icon | Icons |
| .crossHair method name change | Capitalization has been corrected to .crosshair() | Icons | |
| .via method signature changed | via [1-5] icon function has changed method signature, example: // var icon = EMS.Services.StandardIcons.via[2](); var icon = EMS.Icon.via(2); | Icons | |
| .poi method signature changed | .poi(url<string>, color<string>, color<string>, label<string> has been changed to .poi(label<string>, color<EMS.Color>, color<EMS.Color>) | Icons | |
| Markers | New EMS marker type | Addition of EMS.Marker. Use in place of OpenLayers.Marker | Markers |
| Markers Layer | Manage markers directly from map | In v1, markers were added or removed via functions on the markers layer. In v2 these functions are also exposed on the map object. For example: // map.markersLayer.addMarker(marker); map.addMarker(marker); //map.markersLayer.removeMarker(marker); map.removeMarker(marker); | Markers |
| EMS.Services | Services namespace changed | EMS.Services namespace simplified to EMS.Service | |
| All service method signatures simplified | |||
| Geocode Service | Name changed | Name changed to from EMS.Services.Geocoder to EMS.Service.Geocode | Geocoding |
| . | .findAddress() method changed .geocodeIntersection method changed | Both these methods have been replaced by .geocode. Method now accepts a query object rather than several properties | Geocoding |
| .reverseGeocode method changed | Method has been replaced with .reverse(), and now accepts query object rather than several properties | Geocoding | |
| POI Search | Removed | All POI search capability has been removed in v2 | |
| EMS.Services.Itin | Removed | Rank capability moved to EMS.Service.Rank, and route capability moved to EMS.Service.Route | Rank, Route |
| Route service | Changed methods | Multiple method changes. New functions include: route(), segments(), geometry(), .encoded(), .handle() | Route |
| Rank service | New service | New service supersedes Itin.rankPoints() |
These v1 upgrade steps are not exhaustive. If you find any gaps or errors, please forward your findings to ems-support@ems.sensis.com.au