Getting started
Your first successful request in 3 steps.
- 1
Create a complimentary account
Manage and view analytics for all of your API keys.
- 2
Generate an API key
Keep track of usage analytics and authorize requests.
- 3
Make a request
Use your favorite programming language or an UGRC tool. Maybe the API Client?
Key Creation
Once you have a UtahId account, you can generate API keys or claim API keys from your non-Utahid account. Each key is specific to an application you have created; either a browser or desktop based application. Browser based applications run in a web browser. For example, the React geocoding component component dartboard, running on atlas.utah.gov is a browser based application. The request to the UGRC API is created in javascript running inside the browser using the browser's fetch API or with an XHR request. Desktop based applications run on a computer or a server. For example, the API Client is running on your desktop. The request to the UGRC API is called directly or indirectly from a server side programming language or scripting language like Python, Java, or C#.Choosing the key type
Browser
Requests are made by JavaScript running in a browser
Desktop
Requests are made by code or a tool executing on a computer or a server
Choosing a browser key
The UGRC API collects analytics and authenticates requests with your browser key. Since your application is running in a browser, the API key is in public view. To ensure that the analytics are accurate, the key that you create for the application will contain the url the requests originate from.
For example, if your react application is running on atlas.utah.gov, your key pattern will simply equal the DNS name. If your ember application is running on gis.utah.gov/my-application, then your key will also equal the URL.
To get the URL pattern correct when creating the key, reference the table for examples. Be sure to always read the response body when making requests to an endpoint. Failed requests will provide helpful information to correct the issue
| URL Pattern | Description |
|---|---|
| www.example.com www.example.com/ www.example.com/* | Matches all referrers in the domain www.example.com |
| example.com/* | Matches only referrers at example.com, but no subdomains |
| *.example.com | Matches all referrers at all subdomains of example.com |
| example.com/test example.com/test/ example.com/test/* | Matches all referrers in example.com/test/ and all sub paths |
Choosing a desktop key
The UGRC API collects analytics and authorizes requests with your desktop key. To ensure that the analytics are accurate, the key that you create for the application will contain the IP address the requests originate from.
For example, if you are geocoding in ArcGIS Pro, the requests to the API will originate from the IP address assigned to you from your internet service provider. This address is not always static and multiple keys may need to be created over time.
Be sure to always read the response body when making requests to an endpoint. Failed requests will provide helpful information to solve the issue.