Masquerade

A proxy service that impersonates an Esri locator using UGRC data and web services. Use the following URL in Esri products anywhere you would use a geocode service.

https://masquerade.ugrc.utah.gov/arcgis/rest/services/UtahLocator/GeocodeServer

Capabilities

• Single line address geocoding (convert an address to an x,y coordinate). Powered by the UGRC web API.
• Provides typeahead suggestions from the following datasets in Open SGID and returns the centroid:

Name	Dataset	Search Field
Utah House Districts 2022 to 2032	political.house_districts_2022_to_2032	dist
Utah School Board Districts 2022 to 2032	political.school_board_districts_2022_to_2032	dist
Utah Senate Districts 2022 to 2032	political.senate_districts_2022_to_2032	dist
Utah US Congress Districts 2022 to 2032	political.us_congress_districts_2022_to_2032	district
Utah Address Points	location.address_points	name
Utah County Boundaries	boundaries.county_boundaries	name
Utah Municipal Boundaries	boundaries.municipal_boundaries	name
Utah ZIP Code Areas	boundaries.zip_code_areas	zip5
Utah GNIS Place Names	location.gnis_place_names	name

Give Masquerade's awesome searching capabilities a try in this simple web app.

Supported Esri Geocode Service Operations

✅ Find Address Candidates

✅ Geocode Addresses

✅ Suggest

Reverse Geocode has not been implemented. Let us know if you are interested in this feature!

Esri REST API Reference

Common Use Cases

ArcGIS Pro

Locate Pane

If you are looking for a way to quickly navigate your map to Utah addresses or points of interest within ArcGIS Pro, Masquerade can help. By adding UGRC's "Utah Locator (Masquerade)" (hosted in ArcGIS Online) to your project it becomes available to use within the Locate pane. To accomplish this, follow these steps:

1. Add the locator to your project by right-clicking in the "Locators" folder and selecting "Add Locator"
2. Browse to Portal -> ArcGIS Online and then search for "Masquerade"
3. Select "Utah Locator (Masquerade)"
4. Open any map and then go to the "Locate" pane
5. Click on the settings options drop-down button to the left of the search bar and verify that "Utah Locator (Masquerade)" is selected.
6. Start typing in the search box and type-ahead suggestions will start appearing. Click on any suggestion to zoom the map to it.
7. For geocoding single line addresses that do not show up in the type-ahead suggestions, type in the complete address with a zip or city and press enter. (e.g. 123 S Main Street, Holladay).

You should see typeahead suggestions from all of the Open SGID tables above. Here are a few examples:

Batch Geocoding

Once Masquerade has been added as a locator to your project, you can also use it as an input address locator with the Geocode Addresses geoprocessing tool for batch geocoding of address data. This makes Masquerade an easier alternative to the Geocoding Toolbox.

Web AppBuilder/Experience Builder

Masquerade can be used to power the search widget in Web AppBuilder or Experience Builder. To configure, use the following URL as the "Geocoder URL" (WAB) or "Locator URL" (EB) value in the search widget settings:

https://masquerade.ugrc.utah.gov/arcgis/rest/services/UtahLocator/GeocodeServer

Alternatives

UGRC API Client Desktop Application

If you are not already using Esri products, you likely want to check out the Official UGRC API Client. This is a streamlined, stand-alone desktop application that requires no Esri products or licenses.

Development

URLs

Environment	URL
Production	https://masquerade.ugrc.utah.gov/arcgis/rest/services/UtahLocator/GeocodeServer
Staging	https://masquerade-gcedbtv4sa-uc.a.run.app/arcgis/rest/services/UtahLocator/GeocodeServer
Local	https://localhost:5000/arcgis/rest/services/UtahLocator/GeocodeServer

One-time Setup

1. create new python environment: python -m venv env
2. activate new environment: source env/bin/activate (On Windows: .env\Scripts\activate)
3. install dependencies and editable project: pip install -e ".[tests]"
4. create .env (using .env.sample as a template) and populate the WEB_API_KEY variable with a newly created api key. Use type: browser and referer: masquerade.agrc.utah.gov.

MacOS

1. install mkcert brew install mkcert
2. create locally-trusted cert (from root): mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 10.211.55.2
   • 10.211.55.2 is the default ip for the Parallels host machine
3. install the mkcert CA on your local machine
   • mkcert -install
4. install the mkcert CA on another VM
   • copy rootCA.pem and rootCA-key.pem from the directory that is the output of mkcert -CAROOT
   • paste these files into a file on the VM
   • install mkcert on the VM
   • run set CAROOT=<pasted directory> && mkcert -install on the VM (windows terminal works better than a console emulator)

Windows

1. install mkcert choco install mkcert
2. run mkcert -install
3. create locally-trusted cert (from root): mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1

CI/CD

1. Run the terraform code associated with this project.

2. Create dev and prod environments in GitHub repo.

3. Create repo-wide secrets:

   • WEB_API_KEY
   • CODECOV_TOKEN

4. create secrets in github for each environment

   • PROJECT_ID
   • Secrets contained in github-actions-secrets-[prod/dev].txt (output from terraform)

Tests

python -m pytest

Lint

ruff check .

Development Server

./run.sh (macOS) or run.bat (Windows)

Here is a web app that is pointed at https://localhost:5000/ that can be used for testing.

Deployment to GCP

When changes are pushed to either the main (production) or staging branches, the project is automatically built and deployed to the appropriate GCP project (pending passing tests).

Analytics

Data Studio