The Redlink geocoding library provides the means to perform geographical information enhancement based on different services. At the current development state it is possible to do based on Google Maps or Nominatim services:
- geocoding: given a partial address find places which could fit.
- reverse geocoding: providing coordinates find places located at that point.
- lookup: find a place given an ID (specific for the service used).
The library is divided in 5 main artifacts:
- API which contains the basic interface and generic classes to build up the real functionality.
- Google Maps Geocoder an implementation of the geocoder using the Google Maps service.
- Open Street Maps Geocoder an implementation of the geocoder using the Nominatim service.
- Cache Geocoder is a wrapper for any Geocoder which uses basic guava cache to reduce the amount of calls made to the services and improve the response time.
- Proxy Geocoder provides a central geocoding proxy that forwards requests to one of the above providers.
This artifact contains the basic interface and classes to use the library or develop implementations for other geographical services. All the other artifacts on the library depend on this one.
The api artifact provides the basic Geocoder
interface which defines usage of the three operations mentioned before.
final Geocoder geocoder = ...
final List<Place> geocodedPlaces = geocoder.geocode("Jakob Haringer Strasse 3");
final List<Place> reverseGeocodedPlaces = geocoder.reverseGeocode(new LatLon(43.735762, 12.3029561));
final Place lookupPlace = geocoder.lookup("placeID");
Note: the placeId
is implementation/backend specific, which means you can't use a placeId
retrieved from the
OSM based implementation and use it to lookup the place with the GoogleMaps based implementation.
It also provides a basic representation of a geographical Place
coordinate pair.
final LatLon coordinates = new LatLon(47.8229144,13.0404834);
final Place geographicalPlace = new Place("placeID");
geographicalPlace.setAddress("Jakob Haringer Strasse 3");
geographicalPlace.setLatLon(coordinates);
Maven dependency:
<dependency>
<groupId>io.redlink.geocoding</groupId>
<artifactId>geocoding-api</artifactId>
<version>${geocoding.version}</version>
</dependency>
This module implements of the geocoder artifact wrapping Google Maps Services java client. To be able to use the Google Maps Services a valid API key should be provided to the library.
The GoogleMapsGeocoder
object can be instantiate just by the means of the GoogleMapsBuilder
which allows to configure
the specific configuration needed to use the Google Maps Services.
final Geocoder googleGeocoder = GoogleMapsGeocoder.builder()
.setApiKey("Googel_API_key")
.setLocale("de")
.create();
Maven dependency:
<dependency>
<groupId>io.redlink.geocoding</groupId>
<artifactId>geocoding-google</artifactId>
<version>${geocoding.version}</version>
</dependency>
Nominatim services Geocoder implementation, which provides the means to perform the three described operations using the aforementioned service.
final Geocoder nominatimGeocoder = NominatimGeocoder.builder()
.setEmail("example@email.org")
.setLocale("en")
.create();
Maven dependency:
<dependency>
<groupId>io.redlink.geocoding</groupId>
<artifactId>geocoding-osm</artifactId>
<version>${geocoding.version}</version>
</dependency>
The geocoding-cache artifact implements a CacheGeocoder
which actually wraps any other Geocoder object and provides a basic cache for the three supported methods to avoid unnecessary replicated calls to the services and a shorter time response.
final Geocoder cachingGeocoder = CacheGeocoder.builder()
.setGeocoder(geocoder)
.setCacheExpiry(24, TimeUnit.DAYS)
.create();
Maven dependency:
<dependency>
<groupId>io.redlink.geocoding</groupId>
<artifactId>geocoding-cache</artifactId>
<version>${geocoding.version}</version>
</dependency>
The proxy-geocoder consists of two parts: a proxy-server and a client-side implementation to be used instead (or in addition to) the above listed modules.
The Geocoding Proxy is provided as a docker-image and can be launched simply by running
docker run -d -p 8080:8080 -e NOMINATIM_BASE_URL=https://example.com ghcr.io/redlink-gmbh/redlink-geocoding/geocoding-proxy-server
The geocoding providers are autoconfigured using env-variables:
- For Google provide an API-key using
GOOGLE_API_KEY
- For Nominatim, optionally provide
NOMINATIM_BASE_URL
andNOMINATIM_MAIL
- For Caching configure the cache-ttl:
GEO_CACHE_SECONDS
The geocoding-proxy just needs to be configured with the base-url of the proxy-server:
final Geocoder proxyGeocoder = ProxyGeocoder.builder()
.setBaseUri("http://localhost:8080/")
.create();
Maven dependency:
<dependency>
<groupId>io.redlink.geocoding</groupId>
<artifactId>geocoding-proxy</artifactId>
<version>${geocoding.version}</version>
</dependency>
For quick and easy use of the Geocoder
in [spring-boot] projects use the geocoding-spring-boot-autoconfigure
module,
and configure the geocoders with the following application.properties
:
# GoogleMaps Geocoder
## provide either api-key OR client-id and crypto-secret
geocoding.google.api-key=
geocoding.google.client-id=
geocoding.google.crypto-secret=
geocoding.google.channel=
# Nominatim Geocoder
## optional, defaults to public nominatim server by OSM
geocoding.nominatim.base-url=
geocoding.nominatim.email=
## overriding endpoints is optional
geocoding.nominatim.endpoints.geocoding=/search
geocoding.nominatim.endpoints.reverse=/reverse
geocoding.nominatim.endpoints.lookup=/lookup
## optional custom query params
geocoding.nominatim.extra-query-params.<key>=
## optional custom headers
geocoding.nominatim.extra-headers.<header-name>=
# Proxy Geocoder
geocoding.proxy-service.base-url=
# General Options
geocoding.cache-timeout=
geocoding.lang=
geocoding.proxy=
Maven dependency:
<dependencies>
<dependency>
<groupId>io.redlink.geocoding</groupId>
<artifactId>geocoding-spring-boot-autoconfigure</artifactId>
<version>${geocoding.version}</version>
</dependency>
<!-- Add an implementation provider, at least one: -->
<dependency>
<groupId>io.redlink.geocoding</groupId>
<artifactId>geocoding-google</artifactId>
<version>${geocoding.version}</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>io.redlink.geocoding</groupId>
<artifactId>geocoding-osm</artifactId>
<version>${geocoding.version}</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>io.redlink.geocoding</groupId>
<artifactId>geocoding-proxy</artifactId>
<version>${geocoding.version}</version>
<scope>runtime</scope>
</dependency>
<!-- optionally the chache -->
<dependency>
<groupId>io.redlink.geocoding</groupId>
<artifactId>geocoding-cache</artifactId>
<version>${geocoding.version}</version>
<scope>runtime</scope>
</dependency>
</dependencies>
Free use of this software is granted under the terms of the Apache License Version 2.0. See the License for more details.