There are many new functions and features available in v2. Any users who are beginning to upgrade should familiarise themselves with the The Whereis® API (v2)
Map differences between Whereis API v1 and v2
Several changes have been made to align WhereIs API maps with other major mapping APIs. Users may notice the following differences:
- The map projection is changed to Spherical Mercator (previously Ellipsoidal Mercator). Users may notice that at a high zooms the shape of states and regions are changed slightly.
- Individual tile indices (x/y/z) conform with global practices.
- Map tiles are now 256px x 256px, instead of 400 x 400 or 200 x 200
- Map zoom levels have changed. Please refer to Appendix 3 - Zoom Levels
Equivalent zoom levels, Whereis API v1 (left) compared with v2
Authentication token and password
Authentication credentials are valid across all versions and do not need to be changed.
v1 JavaScript to v2 JavaScript
Upgrading to v2 JavaScript is reasonably straightforward. The predominant changes are:
- Some namespaces have changed, e.g. EMS.Services.Map now becomes simply EMS.Map
- The v2 API requires only one import for all JavaScript and CSS artifacts.
- The v2 API extends use of the “profile” property feature, and provides flexible control over dependencies for full build customisation.
For an extensive explanation of the changes between versions and the steps required to upgrade your JavaScript app read Upgrading from Whereis JavaScript API v1:
v1 SOAP to v2 JSON
Whereis v1 SOAP and v2 JSON APIs are not compatible. The following steps will need to be undertaken to upgrade:
Your application’s SOAP client will need to be replaced with a JSON client. JSON doesn’t support the concept of a WSDL, so there is no code generation.
Connect to JSON API as per the instructions here.
Some functionality has been removed, and some has been changed. Review Appendix 6 - v1 SOAP to v2 JSON Operations to determine compatibility.
Data types have changed. For more information read Appendix 7 - v1 SOAP to v2 JSON Data Types.
v1 JSON (1.5.3) to v2 JSON
Whereis v1 JSON and v2 JSON APIs are moderately compatible. Many endpoints are the same and object types are either similar or identical. Some interface behaviour may be different, and response date will change. The following steps will need to be undertaken to upgrade:
Change the base url from http://ems.whereis.com/v1 to http://api.ems.sensis.com.au/v2
Note that all list responses in v2 are paginated. To modify results, pagination controls can be put in the request body.
Request headers remain the same.
Change endpoint mappings as described in Appendix 8 - v1 JSON to v2 JSON Operations
Change request and response body as necessary, as described in Appendix 9 - v1 JSON to v2 JSON Data Types
