Canadian Geographical Names Database Locator

Owned by Diego Cesa de Meira (Unlicensed)
Last updated: Jan 14, 2020 by Alvaro (Unlicensed)
3 min read

The Canadian Geographical Names Database (CGNDB) locator provides an ArcGIS Geocode Service REST API endpoint for the CGNDB API . It acts as an adaptor to allow ArcGIS clients (especially Portal for ArcGIS) to geocode using the CGNDB.

Architecture

The CGNDB locator is a .NET web application hosted in an Azure App Service. The Geocode Service endpoint is registered with Portal for ArcGIS as a geocoding utility service. To geocode using the CGDNB locator, Portal for ArcGIS calls the Geocode Service API, which then calls the CGNDB API. The CGNDB locator also makes calls to the geometry service hosted on the ArcGIS Server instance(s) in the EGIS deployment to perform projections and distance calculations.

 

Software Design

The CGNDB API supports a single method for quering for geographic names. The ArcGIS Geocode Service REST API (ArcGIS API) exposes 4 different methods (FindAddressCandidates, GeocodeAddresses, ReverseGeocode, and Suggest). The CGNDB locator receives requests to the ArcGIS API and transforms these requests to calls to the CGNDB API method.

Note: Currently the ReverseGeocode method is not implemented. There is not yet a user story in EGIS that requires it.

GeocodeServer

The root endpoint returns the service definition. The service definition is contained in a JSON file that was generated by creating an single field address locator on the CGNDB dataset in ArcGIS Pro and publishing it to Portal for ArcGIS. The JSON file contains the service definition for that locator.

Query Parameters

The ArcGIS API and the CGNDB have some similar parameters that are treated differently in some instances.

searchExtent / bbox

The ArcGIS REST API's searchExtent parameter and the CGNDB API's bbox parameter represent the area in which to search for results. Candidates not within this area are not included in the result. These parameters are equivalent between the two APIs.

{location, distance} / {lat, lon, radius}

These sets of parameters represent a location and a distance from the location for a query. However, the two APIs treat these parameters differently, semantically.

The ArcGIS API uses location and distance parameters in conjunction with the searchExtent parameter. The ArcGIS API searches for candidates within the searchExtent, and then includes those candidates within distance of location at the top of the result set returned.

The CGNDB API uses either the bbox or the combination of lat, lon, and radius parameters, but not both.

The CGNDB locator uses the searchExtent parameter to query the CGNDB API with the bbox parameter. It then sorts the results by increasing geodesic distance from the location.

Note: Currently, the CGNDB locator cannot be used from within ArcGIS Pro. Additional debugging is required to determine why this is the case.

Software Development / Publishing

  1. Open the CGNDB solution available in the eGIS Repo

     

     

  2. Right click on the Solution → Publish

     

  3. Choose the Publish Profile

     

    Right now, to be able to debug directly from Azure Cloud, use the Prod Profile. However, in case there is already a solution in Prod, choose another profile. This is to be fixed

  4. Once the Publish is completed, a web browser will automatically open. Get this http address and set in the eGIS Portals, starting by testing on DEV. Go to Organization → Settings → Utilities → Geocoding → Add Locator

     

  5. Ready to run.