# Geocoding Profile Transformation Service
Transformation to convert
- geo coordinates into human readable string address (reverse geocoding)
- string address description into geo coordinates (geocoding)
# Reverse Geocoding
The reverse geocoding is applied when the channel updates the Location with latitude and longitude geo coordinates.
These will be resolved into a human readable address.
Reverse geocoding is throttled by the profile with resolveInterval to avoid frequent calling.
# Geocoding
Geocoding is applied if you send a string command towards the item. The API is translating this search string into geo coordinates which are send via the channel towards the handler. Of course this makes sense only if the channel is declared as writable. Formulate your string command as precise as possible to avoid ambiguous results. E.g. Springfield US command will deliver multiple results and only one is chosen for the transformation.
Geocoding is not throttled by the profile.
# Configuration
| Configuration Parameter | Type | Description |
|---|---|---|
provider | text | Provider which is used to execute geocoding request |
resolveInterval | text | Interval of reverse geocoding executions. Minimum: 1 minute |
format | text | Country specific address formatting |
language | text | Preferred language of the result. Only necessary if openHAB locale settings shall be overwritten |
Select provider which shall be used to resolve addresses.
Currently one provider Nominatim / OpenStreetMap is available which is the default option.
The resolveInterval defines the minimum time between two reverse geocoding transformations.
An external API is called to resolve the geo coordinates and it shall not be queried too frequent.
Channel updates within the Interval are omitted.
After the configured interval is expired the last received location will be transformed.
Minimum configurable interval is 1 minute.
Default is 5 minutes (5m).
Select preferred display format for reverse geocoding.
Options:
- Address format Rest of World
address_row:streethouse-number,postcodecitydistrictas default - Address format US/UK
address_us:house-numberstreet,citydistrictpostcode - Unformatted JSON response:
json
Note that address fields (opens new window) may be missing e.g. for rural areas.
The API calls are performed with your openHAB locale settings.
This can be overwritten with language configuration parameter using Java Locale format (opens new window).
# Provider
# Nominatim / OpenStreetMap Provider
Geocoding transformation provider using Nominatim API for OpenStreetMap (opens new window) to resolve
- geo coordinates into a human readable string (reverse geocoding (opens new window))
- an address string into geo coordinates (geocoding (opens new window))
You must respect the Nominatim Usage Policy (opens new window)!
You need to estimate your call frequency towards the Nominatim provider.
For reverse geocoding the configuration parameter resolveInterval with minimum resolve time of 1 minute shall fulfill the throttling requirements.
For geocoding there's no throttling.
Each user needs to respect the maximum allowed frequency of 1 call per second.
The required User-Agent is provided by this transformation profile.
Credits to Nominatim (opens new window) and OpenStreetMap (opens new window) to provide this free service!
# Example
String <itemName> { channel="<locationChannelUID>"[profile="transform:geocoding",provider="nominatim-osm",format="us_address",resolveInterval="10m",language="en-US"]}