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:
The library is divided in 5 main artifacts:
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("[email protected]")
.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:
GOOGLE_API_KEY
NOMINATIM_BASE_URL
and NOMINATIM_MAIL
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.