Geocoder Service

The geocoder service resolves geolocation information in Horizon. Horizon also supports several external geocoder services. By default, geolocation resolution is disabled.

When enabled, geolocation is performed based on the presence of address-related asset fields assigned to a node. The geocoder service runs only against nodes that are missing latitude and longitude fields, but that do not have street address fields. See Provisioning for more information on defining asset fields in a requisition.

Resolved coordinates are stored in the database as node asset fields, but the geocoder service does not update requisitions.

Address-based geocoding

To enable or configure the geocoder service, use the web-based configuration tool:

In the Horizon web UI, click the gear symbol in the top-right of the page.
Under Provisioning, select Configure Geocoder Service.
You can use one of three geocoder services: Google, MapQuest, or Nominatim. To enable one, toggle the corresponding switch to On.
Navigate to the appropriate tab and configure the service:
- Google:
  1. Choose whether to authenticate using the clientId and signature.
  2. Type the API key and configure the timeout.
  3. Choose whether to use the system proxy.
- MapQuest:
  1. Type the API key.
  2. Choose whether to use the system proxy.
- Nominatim:
  1. Type your email address.
  2. (Optional) Configure the user agent and referer.
  3. Read and accept the terms of use.
  4. Choose whether to use the system proxy.
Click Save.

If you would prefer to manually edit the configuration files, you can set the active geocoder service via the activeGeocoderId property in ${OPENNMS_HOME}/etc/org.opennms.features.geocoder.cfg.

Google

The Google geocoder API is a service that provides geocoding and reverse geocoding of addresses. The Google geocoder API requires at least an apiKey or a clientId and signature. For more details, see the official Google documentation.

Google geocoder API properties
Property	Description	Type	Default Value
Required
apiKey	The API key that the Google Cloud platform provides. Required only if `useEnterpriseCredentials` is false.	String	Empty
clientId	The Google geocoder API client ID. Required only if `useEnterpriseCredentials` is true.	String	Empty
signature	The Google geocoder API signature.	String	Empty
Optional
useEnterpriseCredentials	If authentication with `clientId` and `signature` is required, set this to `true`.	Boolean	false
useSystemProxy	Should the system-wide proxy settings be used? Configure the system proxy settings in opennms.conf.	Boolean	false
timeout	The connection timeout, in milliseconds, during which the geocoder tries to resolve a single geolocation.	Integer	500

These properties are recorded in ${OPENNMS_HOME}/etc/org.opennms.features.geocoder.google.cfg.

MapQuest

The MapQuest geocoder lets Horizon associate latitude and longitude coordinates with an actual address (geolocation).

To use MapQuest, you must register and sign up for an API key. For more details, refer to the official MapQuest documentation.

MapQuest geocoder API properties
Property	Description	Type	Default Value
Required
apiKey	The API key.	String	Empty
url	The URL template for the MapQuest geocoder API. The `apikey` and `query` strings are substituted before making the request.	String	`http://www.mapquestapi.com/geocoding/v1/address?format=json&key={apikey}&maxResults=1&location={query}`
Optional
useSystemProxy	Should the system-wide proxy settings be used? Configure the system proxy settings in opennms.conf.	Boolean	false

These properties are recorded in ${OPENNMS_HOME}/etc/org.opennms.features.geocoder.mapquest.cfg.

Nominatim

Nominatim is a tool that searches OpenStreetMap data and creates synthetic addresses for OpenStreetMap points. It lets Horizon look up coordinates for a given address. For more information, see the official Nominatim documentation.

Be sure to check the Nominatim Usage Policy before using the geocoder service.

Nominatim geocoder service properties
Property	Description	Type	Default Value
Required
acceptUsageTerms	To use the Nominatim geocoder service, you must accept the Nominatim Usage Policy. Set this property to `true` to agree to their terms.	Boolean	false
url	The URL template for the Nominatim geocoder API. The `email` and `query` strings are substituted before making the request.	String	`https://nominatim.openstreetmap.org/search?format=json&email={email}&limit=1&q={query}`
email	Provide this in case you are making a large number of requests. Alternatively, you can provide this information in the `userAgent` property.	String	Empty
referer	Note that either `referer` or `userAgent` is required.	String	Empty
userAgent	Note that either `referer` or `userAgent` is required.	String	OpenNMS-NominatimGeocoderService/2.0
Optional
useSystemProxy	Should the system-wide proxy settings be used? Configure the system proxy settings in system properties.	Boolean	false

These properties are recorded in ${OPENNMS_HOME}/etc/org.opennms.features.geocoder.nominatim.cfg.

IP-based geocoding

An alternative to the geocoder service is the GeoIP provisioning adapter. This adapter can look up coordinates based on IP address, and will update the node’s requisition definition, bypassing the need for the geocoder service to determine location based on address.