Using AGRC's new Web Mercator Services in Your Web Maps

Recently, AGRC, in conjunction with DNR, hosted an open house discussing AGRC’s basemap and imagery strategies. During this open house, AGRC discussed details of new web mercator (WGS84) basemaps as the default presentation layer moving forward. Most of the UTM basemaps have been converted to web mercator and are hosted and served through discover.agrc.utah.gov. The plan is to sunset the UTM basemaps at the end of 2016.

While upgrading the UTM basemaps to web mercator, AGRC decided to modify the map services offered. Based on usage analytics and user feedback, the hillshade and vector basemap were removed. The Hybrid service was replaced by combining the Google imagery service and a new overlay service (a long-requested feature allowing users to “sandwich” their data within the basemap). The Lite, Terrain and Topo basemaps were converted with no changes. Finally, there is a new Color Infrared service derived from the 2011 NAIP.

The new services are delivered via WMTS. WMTS is an OGC standard for delivering tiled map data. The Esri JavaScript API provides a class for consuming with these services called a WebTiledLayer. Using this class is as simple as passing in the URL to the WMTS service with the appropriate level, column and row tokens. For example:

You’ll notice that the URL to the service includes a quad word that is unique to your organization and project. If you don’t have an account set up or a quad word, you can register on our website to get started. If you are planning on putting your quad word into a website or somewhere that it is publicly accessible, you will need to contact Jake Adams from AGRC at jdadams@utah.gov to receive a special quad word for licensing reasons.

All of our base maps are cached from levels 5 through 19 with the exception of Topo which is cached to level 17. The Google imagery service has an additional level, 20, to allow users to take full advantage of the high resolution (6” pixels). You can see a table of min and max zoom levels on the discover.agrc.utah.gov website. This can create problems when using the Esri JavaScript API map class. The map sets the zoom levels based on the first layer that is added to it. For example, if a service is added to the map that is cached to level 19 and then the Google imagery service is added, the map will not allow you to zoom into level 20.

WebTiledLayer and WMTS integrate together slightly different than ArcGISTiledMapServiceLayer and ArcGIS Server cached map services. The main caveat being ArcGIS services store metadata about the service that WebTiledLayers do not. The piece of metadata that will affect developers the most is the cache level information. WebTiledLayers cache levels are based on a suggested set that is common amongst popular tile providers. The suggested set uses 0 through 19. If the tile set you are using deviates from these levels, you will be responsible for setting those values or you will not be given the UI to see the full tile set. As you can see in the sample below it takes a fair amount of work.

AGRC has a new widget called the layer-selector that handles these issues as well as makes working with basemaps more streamlined. It’s main purpose is to provide users the ability to quickly switch between basemaps and toggle associated overlays.

Basemaps and overlays can be defined by passing in layer factories that define a constructor and parameters.

Alternatively, developers can pass in their discover.agrc.utah.gov quad word and simple token strings that are associated with each of the AGRC basemaps. This greatly simplifies the amount of code required.

We hope that this new widget will help ease your transition to the new web mercator services. The layer selector code is on Github and is registered on bower as "agrc-layer-selector". More documentation and examples can be found in the repository. If you run into any trouble please use the issue tracker.