AGRC offers a variety of mapping-related web services that make it easy to add authoritative Utah web maps to your applications. The two most popular are our base maps and geocoding service. These web services, together with a custom map service that shows your own agency/business-specific data, can add great geographic context to your web applications.

This post will show you how simple it is to leverage AGRC's services with JavaScript. We will develop a simple web app that contains a dynamic map and simple address finding controls. Please note that we've added a simple glossary of terms at the bottom of this page.

ESRI JavaScript API

The first thing to do is create a simple .html page and import ESRI's ArcGIS API for JavaScript. You can load their API by a CSS file:

<link rel="stylesheet" href="https://serverapi.arcgisonline.com/jsapi/arcgis/3.5/js/esri/css/esri.css">

and a script file: 

<script src="https://serverapi.arcgisonline.com/jsapi/arcgis/3.5/"></script>

This will load all necessary dependencies including Dojo into your application. Dojo is a widely used javascript library containing commonly used functionality for cross-browser compatible user interface presentation and management. Because it's built on top of Dojo, ESRI's API also employs the new Asynchronous Module Definition (AMD) standard for loading external JavaScript libraries. With both Dojo and ESRI development teams using AMD, it is highly recommended that you also use the AMD loading syntax, as this should maximize the life-expectancy for the map-service consuming code that you write. All code examples in this post will be using the new AMD syntax. If you are unfamiliar with AMD you may want to check out Dojo's excellent tutorial on the subject.

Base Maps

AGRC provides seven high-quality, pre-rendered base map services. These services are published through ESRI's ArcGIS Server software. The service directory end points can be found here:

Adding one of these services to a map is relatively easy. First, we need to import a few ESRI modules. Then create a new map and tiled layer. Finally, we add the newly created layer to the map. Here's what the code looks like:

Geocoding (Address Matching)

To geocode an address means to find it's corresponding geographic coordinates (think latitude and longitude). AGRC provides a highly authoritative service for geocoding addresses which is regularly updated from road centerline and address point data available to AGRC through its local government partners across the state. In addition, the service has been optimized for the State of Utah's somewhat unique placename and addressing system conventions.

Before you can use any of AGRC's web API services you will need to create an account and an API key for your domain. Check out the Getting Started Guide for more information. Once you have a key you can start using services such as geocoding. Here's an example of a typical geocoding request that finds coordinates for 123 S Main St, SLC:

There are samples of how to use this service in several popular languages in our GeocodingSample GitHub repository.

Perhaps the easiest way for you to use this service is to use the FindAddress widget in our AGRC Dojo Widget Library. You can do this by adding a config object to your require call that defines an agrc package and its location. Here we have it pointing at the 'agrc' package on our CDN resource:

Once we have defined our agrc package, we can import modules just like any other package. This example shows how to import the FindAddress widget and initializing it with our map object and our AGRC Web API key:

Custom Data Overlays

The next step in our demo will be to add a data overlay on top of the base map. To do this you need to have access to a map web service, that points at your own data on a server and makes it accessible to web-based map requests. This is most commonly done using ESRI's ArcGIS Server or similar software or via cloud-hosted data and services platform such as ArcGIS Online. If you do not have access to this software, you may want to contact us about getting a service set up on our servers for you. For this demo we will use a service that we host that shows the Utah Division of Fleet Operations' vehicle refueling sites around the state. The endpoint for this service is here:

To add this map service to our map we need to import the esri/layers/ArcGISDynamicMapServiceLayer module and create a new layer using the url to the service. Then we can add it to the map. Here's what it looks like:

Spatial Queries

Another useful AGRC web API service is the ability to search for geographic features in any of the datasets in the SGID. This functionality is found in the Search service. You can check out the api docs for an example request and response. We will use this service to display a message that tells us what city we are in when we click on the map. Within the map's click event we pass the coordinates from the map click event to the search service along with the feature class name (SGID10.BOUNDARIES.Municipalities) and the field name (NAME). Then when the service returns, we populate the page with the data. Here's what it looks like:

See the Pen QBxGPX by Scott Davis (@stdavis) on CodePen.

Please note that the api has services for accessing schema information for SGID database server content. Feature class (map data layer) names are available by category (example request for feature classes in Political category). With a feature class name and category, the names of the fields/columns can be accessed via the Feature Class Attribute Names service (example for Municipalities feature class).

Wrap-up

This is just a small sampling of what AGRC has to offer in terms of web mapping services. If you are interested in an advanced example of one of our web applications you can check out our AGRCJavaScriptBoilerPlate. A presentation detailing how this sample was engineered was given at the ESRI Dev Summit in March 2013.