
= Geocoder Service
:description: Learn how to enable the geocoder service in {page-component-title} to resolve geolocation information with Google, MapQuest, and Nominatim.

The geocoder service resolves geolocation information in {page-component-title}.
{page-component-title} 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 xref:deep-dive/provisioning/directed-discovery.adoc[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:

. Click menu:Integrations[Geocoding Services] in the side menu.
. Or, click menu:Administration[Configure OpenNMS] in the side menu, then under *Provisioning*, click *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:*
... 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.
... Read and accept the terms of use.
... Choose whether to use the system proxy.
. Click *Save*.

NOTE: 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 https://developers.google.com/maps/documentation/javascript/get-api-key[official Google documentation].

[caption=]
.Google geocoder API properties
[cols="2,3,1,1"]
|===
| Property  | Description | Type  | Default Value

4+|*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_

4+| *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 xref:deep-dive/admin/configuration/system-properties.adoc[opennms.conf].
| Boolean
| false

| timeout
| The connection timeout, in milliseconds, during which the geocoder tries to resolve a single geolocation.
| Integer
| 500
|===

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

=== MapQuest

The MapQuest geocoder lets {page-component-title} 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 https://developer.mapquest.com/documentation/geocoding-api/[official MapQuest documentation].

[caption=]
.MapQuest geocoder API properties
[cols="1,3,1,2"]
|===
| Property  | Description | Type  | Default Value

4+| *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}&amp;maxResults=1&location=\{query}`

4+| *Optional*

| useSystemProxy
| Should the system-wide proxy settings be used?
Configure the system proxy settings in xref:deep-dive/admin/configuration/system-properties.adoc[opennms.conf].
| Boolean
| false
|===

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

=== Nominatim

https://wiki.openstreetmap.org/wiki/Nominatim[Nominatim] is a tool that searches OpenStreetMap data and creates synthetic addresses for OpenStreetMap points.
It lets {page-component-title} look up coordinates for a given address.
For more information, see the https://nominatim.org/release-docs/develop/[official Nominatim documentation].

IMPORTANT: Be sure to check the https://operations.osmfoundation.org/policies/nominatim/[Nominatim Usage Policy] before using the geocoder service.

[caption=]
.Nominatim geocoder service properties
[cols="1,3,1,2"]
|===
| Property  | Description | Type  | Default Value

4+| *Required*

| acceptUsageTerms
| To use the Nominatim geocoder service, you must accept the https://operations.osmfoundation.org/policies/nominatim/[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&amp;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

4+| *Optional*

| useSystemProxy
| Should the system-wide proxy settings be used?
Configure the system proxy settings in xref:deep-dive/admin/configuration/system-properties.adoc[system properties].
| Boolean
| false
|===

NOTE: 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 xref:reference:provisioning/adapters/geoip.adoc[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.
