Geocoder Service

The geocoder service resolves geolocation information within Horizon. Horizon 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 will run only against nodes that are missing latitude and longitude fields, but that do have street address fields. See Provisioning for steps to define asset fields on 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:

  1. In the Horizon web UI, click the gear symbol in the top-right of the page.

  2. Under Provisioning, select Configure Geocoder Service.

  3. You can use one of three geocoder services: Google, MapQuest, or Nominatim. To enable one, turn the corresponding switch On.

  4. Navigate to the appropriate tab and configure the service:

    • Google:

      • Choose whether to authenticate using the clientId and signature.

      • Type the API key and configure the timeout.

      • Choose whether to use the system proxy.

    • MapQuest:

      • Type the API key.

      • Choose whether to use the system proxy.

    • Nominatim:

      • Type your email address.

      • (Optional) Configure the user agent and referer.

      • Accept the terms of use.

      • Choose whether to use the system proxy.

  5. 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.

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 (geolocation). 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.

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.

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.