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 only run against nodes that are missing latitute and longitude fields but do have street address fields. See the provisioning documentation 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. In the web UI, click the Gear Icon  Provisioning  Configure Geocoder Service.

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

Nominatim

For more details, see the official documentation and check the Nominatim Usage Policy before using the geocoder service.

Property Description Type Default

Required

acceptUsageTerms

To use the Nominatim Geocoder Service you must accept the Nominatim Usage Policy. Set this 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

According to the official documentation, provide this in case you are making a large number of requests. Alternatively, provide this information in the userAgent property.

String

empty string

referer

Note that either referer or userAgent is required.

String

empty string

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 requires at least an apiKey or a clientId and signature. For more details, see the official documentation.

Property Description Type Default

Required

apiKey

The apiKey provided by the Google Cloud Platform. Required only if useEnterpriseCredentials is false.

String

empty string

clientId

The Google Geocoder API client ID. Required only if useEnterpriseCredentials is true.

String

empty string

signature

The Google Geocoder API signature.

String

empty string

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

For more details, refer to the official documentation.

Property Description Type Default

Required

apiKey

The API key.

String

empty string

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.