Authentication overview

Authentication for the Utah AGRC Address Geocoding Web API is primarily handled through API keys. These keys serve as a credential to identify the calling application and authorize its requests to the geocoding service. The AGRC API key system is designed for straightforward integration, allowing developers to quickly begin using the service for geocoding addresses within Utah.

When you register for an API key, it is associated with your account and tracks your usage against the established quota, including the free tier of 15,000 requests per month. Exceeding this free tier transitions to a tiered pricing model, which commences at $20 per month for up to 50,000 requests per month. For detailed pricing information, refer to the AGRC Address Geocoding Service Information page.

The API key must be included with every request to the geocoding endpoint. Failure to provide a valid API key will result in authentication errors, preventing access to the geocoding functionalities. The AGRC system relies on these keys to manage access control and ensure fair usage of its resources. This approach is common in many web services, as highlighted in general API security practices for API Gateway and security guidelines.

Supported authentication methods

The Utah AGRC Address Geocoding Web API primarily supports API key authentication. This method involves generating a unique key through the AGRC developer portal and including it as a parameter in your API requests. While other authentication mechanisms exist across various API ecosystems, AGRC has standardized on API keys for simplicity and ease of use for its geocoding services.

Method When to Use Security Level
API Key Accessing the Utah AGRC Address Geocoding Web API Moderate (dependent on key management)

API keys are suitable for client-side applications or server-side integrations where the key can be securely stored and transmitted. They provide a basic level of authentication by identifying the user or application making the request. However, it is crucial to manage API keys with care to prevent unauthorized access, as discussed in the AGRC how-to-use-our-data documentation.

Getting your credentials

To obtain an API key for the Utah AGRC Address Geocoding Web API, you typically follow these steps:

  1. Visit the AGRC Developer Portal: Navigate to the Utah AGRC geocoding service page, which provides links and information for accessing the service.
  2. Register for an Account: If you don't already have one, you will need to register for a user account with AGRC. This usually involves providing an email address and creating a password.
  3. Request an API Key: Once logged in, locate the section for API key generation or management. You may be prompted to provide details about your application or project for which the key is intended.
  4. Generate Key: Follow the instructions to generate your unique API key. The key will be a string of alphanumeric characters.
  5. Record Your Key: Securely store your API key immediately after generation. AGRC typically displays the key once, and you may not be able to retrieve it again directly from the portal. If lost, you might need to generate a new one.

The specific steps and interface may vary slightly, so it is always recommended to consult the official AGRC API documentation for the most up-to-date instructions on credential setup.

Authenticated request example

Once you have obtained your API key, you can include it in your requests to the Utah AGRC Address Geocoding Web API. The API key is typically passed as a query parameter named apiKey in the request URL. Below are examples demonstrating how to make an authenticated request using common programming languages.

JavaScript (Fetch API)

const address = '4137 South 500 West, Murray, UT';
const apiKey = 'YOUR_API_KEY_HERE'; // Replace with your actual API key

fetch(`https://api.mapserv.utah.gov/api/v1/geocode/${encodeURIComponent(address)}?apiKey=${apiKey}`)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Python (Requests library)

import requests
import urllib.parse

address = '4137 South 500 West, Murray, UT'
api_key = 'YOUR_API_KEY_HERE' # Replace with your actual API key

encoded_address = urllib.parse.quote(address)
url = f"https://api.mapserv.utah.gov/api/v1/geocode/{encoded_address}?apiKey={api_key}"

response = requests.get(url)
if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code} - {response.text}")

C# (.NET HttpClient)

using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Web;

public class AgrcGeocodeService
{
    private static readonly HttpClient client = new HttpClient();

    public static async Task GetGeocodeData(string address, string apiKey)
    {
        string encodedAddress = HttpUtility.UrlEncode(address);
        string url = $"https://api.mapserv.utah.gov/api/v1/geocode/{encodedAddress}?apiKey={apiKey}";

        try
        {
            HttpResponseMessage response = await client.GetAsync(url);
            response.EnsureSuccessStatusCode(); // Throws an exception if not a success code
            string responseBody = await response.Content.ReadAsStringAsync();
            Console.WriteLine(responseBody);
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Error: {e.Message}");
        }
    }

    public static async Task Main(string[] args)
    {
        string addressToGeocode = "4137 South 500 West, Murray, UT";
        string yourApiKey = "YOUR_API_KEY_HERE"; // Replace with your actual API key
        await GetGeocodeData(addressToGeocode, yourApiKey);
    }
}

These examples demonstrate the fundamental method of including the apiKey parameter in your web requests. Always replace 'YOUR_API_KEY_HERE' with your actual, securely obtained API key.

Security best practices

Protecting your Utah AGRC API key is critical to prevent unauthorized access to your account and services, and to avoid unexpected usage charges. Adhere to the following security best practices:

  1. Do Not Embed Keys Directly in Client-Side Code: Avoid hardcoding API keys directly into public client-side code (e.g., JavaScript in web pages or mobile apps). These keys can be easily extracted by malicious actors. Instead, use a backend proxy or serverless function to make API calls, where the key can be securely stored and managed.
  2. Use Environment Variables for Server-Side Applications: For server-side applications, store your API keys as environment variables rather than directly in your codebase. This prevents the key from being committed to version control systems like Git and makes it easier to manage keys across different deployment environments.
  3. Restrict API Key Usage: If AGRC provides options to restrict API key usage (e.g., by IP address or HTTP referrer), configure these restrictions. This ensures that even if a key is compromised, it can only be used from authorized locations or domains. Check the AGRC API documentation for available security features.
  4. Regularly Rotate API Keys: Periodically generate new API keys and revoke old ones. This practice reduces the risk associated with a compromised key, as its validity period will be limited.
  5. Monitor API Usage: Regularly review your API usage logs and billing statements (if applicable) to detect any unusual activity that might indicate a compromised key. The AGRC pricing page outlines the tiered pricing for usage beyond the free tier.
  6. Implement Secure Key Storage: Store API keys in secure, encrypted storage mechanisms. Avoid plain-text storage on disk. For cloud deployments, consider using secret management services provided by cloud providers (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault). Google Cloud's secrets management documentation provides a good overview of these practices.
  7. Handle Errors Gracefully: Implement robust error handling in your application. If an API call fails due to an invalid or missing API key, ensure your application handles this securely without exposing sensitive information.

By following these best practices, you can significantly enhance the security posture of your applications integrating with the Utah AGRC Address Geocoding Web API.