The instructions on this page are dated. Using Discover services with the Esri JavaScript API v4.x contains more current information.
Recently, UGRC, in conjunction with DNR, hosted an open house discussing UGRC’s base map and imagery strategies. During this open house, UGRC discussed details of new web mercator (WGS84) base maps as the default presentation layer moving forward. Most of the UTM base maps have been converted to web mercator and are hosted and served through discover.agrc.utah.gov. The plan is to sunset the UTM base maps at the end of 2016.
While upgrading the UTM base maps to web mercator, UGRC decided to modify the map services offered. Based on usage analytics and user feedback, the hillshade and vector base map 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 base map). The Lite, Terrain and Topo base maps 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 UGRC 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.
UGRC has a new widget called the layer-selector that handles these issues as well as makes working with base maps more streamlined. It’s main purpose is to provide users the ability to quickly switch between base maps and toggle associated overlays.
Base maps 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 UGRC base maps. 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.