{"id":14973036,"url":"https://github.com/redlink-gmbh/redlink-geocoding","last_synced_at":"2025-10-26T20:32:35.604Z","repository":{"id":37964322,"uuid":"458140946","full_name":"redlink-gmbh/redlink-geocoding","owner":"redlink-gmbh","description":"Redlink Geocoding Library","archived":false,"fork":false,"pushed_at":"2024-10-29T12:47:56.000Z","size":807,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-10-29T15:16:36.657Z","etag":null,"topics":["asl","geocoding","google-maps-api","java","library","openstreetmap","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redlink-gmbh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-11T10:27:56.000Z","updated_at":"2024-10-29T12:47:06.000Z","dependencies_parsed_at":"2024-02-19T14:28:53.228Z","dependency_job_id":"1c2a51d6-4423-4905-9924-d1eeeb7a4787","html_url":"https://github.com/redlink-gmbh/redlink-geocoding","commit_stats":{"total_commits":394,"total_committers":6,"mean_commits":65.66666666666667,"dds":"0.47208121827411165","last_synced_commit":"088e9ae1c3acb4b4f9a2d04e4198342d31b86c8e"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redlink-gmbh%2Fredlink-geocoding","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redlink-gmbh%2Fredlink-geocoding/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redlink-gmbh%2Fredlink-geocoding/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redlink-gmbh%2Fredlink-geocoding/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redlink-gmbh","download_url":"https://codeload.github.com/redlink-gmbh/redlink-geocoding/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238397260,"owners_count":19465145,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asl","geocoding","google-maps-api","java","library","openstreetmap","spring-boot"],"created_at":"2024-09-24T13:47:59.533Z","updated_at":"2025-10-26T20:32:35.241Z","avatar_url":"https://github.com/redlink-gmbh.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Redlink Geocoding Library\n\n[![Build, Test \u0026 Publish](https://github.com/redlink-gmbh/redlink-geocoding/actions/workflows/maven-build-and-deploy.yaml/badge.svg)](https://github.com/redlink-gmbh/redlink-geocoding/actions/workflows/maven-build-and-deploy.yaml)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=redlink-gmbh_redlink-geocoding\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=redlink-gmbh_redlink-geocoding)\n\n[![Maven Central](https://img.shields.io/maven-central/v/io.redlink.geocoding/geocoding.png)](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.redlink.geocoding%22)\n[![Sonatype Nexus (Snapshots)](https://img.shields.io/nexus/s/https/oss.sonatype.org/io.redlink.geocoding/geocoding.png)](https://oss.sonatype.org/#nexus-search;gav~io.redlink.geocoding~~~~)\n[![Javadocs](https://www.javadoc.io/badge/io.redlink.geocoding/geocoding.svg)](https://www.javadoc.io/doc/io.redlink.geocoding/geocoding)\n[![Apache 2.0 License](https://img.shields.io/github/license/redlink-gmbh/redlink-geocoding.svg)](https://www.apache.org/licenses/LICENSE-2.0)\n\nThe Redlink geocoding library provides the means to perform geographical \ninformation enhancement based on different services. At the current \ndevelopment state it is possible to do based on [Google Maps](https://developers.google.com/maps/documentation/geocoding/intro) \nor [Nominatim](https://wiki.openstreetmap.org/wiki/Nominatim) services:\n \n* _geocoding_: given a partial address find places which could fit.\n* _reverse geocoding_: providing coordinates find places located at that point.\n* _lookup_: find a place given an ID (specific for the service used).\n\nThe library is divided in 5 main artifacts:\n\n* API which contains the basic interface and generic classes to build up the real functionality.\n* Google Maps Geocoder an implementation of the geocoder using the [Google Maps](https://developers.google.com/maps/documentation/geocoding/intro) service.\n* Open Street Maps Geocoder an implementation of the geocoder using the [Nominatim](https://wiki.openstreetmap.org/wiki/Nominatim) service.\n* 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.\n* Proxy Geocoder provides a central geocoding proxy that forwards requests to one of the above providers.\n\n## General (API)\nThis 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.\n\nThe api artifact provides the basic `Geocoder` interface which defines usage of the three operations mentioned before.\n\n```java\nfinal Geocoder geocoder = ...\n\nfinal List\u003cPlace\u003e geocodedPlaces = geocoder.geocode(\"Jakob Haringer Strasse 3\");\nfinal List\u003cPlace\u003e reverseGeocodedPlaces = geocoder.reverseGeocode(new LatLon(43.735762, 12.3029561));\nfinal Place lookupPlace = geocoder.lookup(\"placeID\");\n```\n\n**Note:** the `placeId` is implementation/backend specific, which means you can't use a `placeId` retrieved from the \nOSM based implementation and use it to lookup the place with the GoogleMaps based implementation. \n\nIt also provides a basic representation of a geographical `Place` coordinate pair.\n\n```java\nfinal LatLon coordinates = new LatLon(47.8229144,13.0404834);\nfinal Place geographicalPlace = new Place(\"placeID\");\ngeographicalPlace.setAddress(\"Jakob Haringer Strasse 3\");\ngeographicalPlace.setLatLon(coordinates);\n```\n\nMaven dependency:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.redlink.geocoding\u003c/groupId\u003e\n    \u003cartifactId\u003egeocoding-api\u003c/artifactId\u003e\n    \u003cversion\u003e${geocoding.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Google Maps Geocoder\nThis module implements of the geocoder artifact wrapping Google Maps Services java [client](https://github.com/googlemaps/google-maps-services-java).\nTo be able to use the Google Maps Services a valid API key should be provided to the library.\n\nThe `GoogleMapsGeocoder` object can be instantiate just by the means of the `GoogleMapsBuilder` which allows to configure\nthe specific configuration needed to use the Google Maps Services.\n\n\n```java\nfinal Geocoder googleGeocoder = GoogleMapsGeocoder.builder()\n        .setApiKey(\"Googel_API_key\")\n        .setLocale(\"de\")\n        .create();\n```\n\nMaven dependency:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.redlink.geocoding\u003c/groupId\u003e\n    \u003cartifactId\u003egeocoding-google\u003c/artifactId\u003e\n    \u003cversion\u003e${geocoding.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Open Street Maps Geocoder\n[Nominatim](http://wiki.openstreetmap.org/wiki/Nominatim) services Geocoder implementation, which provides the means to perform the three described operations using the aforementioned service.\n\n```java\nfinal Geocoder nominatimGeocoder = NominatimGeocoder.builder()\n               .setEmail(\"example@email.org\")\n               .setLocale(\"en\")\n               .create();\n```\n\nMaven dependency:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.redlink.geocoding\u003c/groupId\u003e\n    \u003cartifactId\u003egeocoding-osm\u003c/artifactId\u003e\n    \u003cversion\u003e${geocoding.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Cache Geocoder\nThe 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.\n\n```java\nfinal Geocoder cachingGeocoder = CacheGeocoder.builder()\n               .setGeocoder(geocoder)\n               .setCacheExpiry(24, TimeUnit.DAYS)\n               .create();\n```\n\nMaven dependency:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.redlink.geocoding\u003c/groupId\u003e\n    \u003cartifactId\u003egeocoding-cache\u003c/artifactId\u003e\n    \u003cversion\u003e${geocoding.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Proxy Geocoder\nThe proxy-geocoder consists of two parts: a proxy-server and a client-side implementation to be used\ninstead (or in addition to) the above listed modules.\n\n### Proxy Server\nThe Geocoding Proxy is provided as a docker-image and can be launched simply by running\n```shell\ndocker run -d -p 8080:8080 -e NOMINATIM_BASE_URL=https://example.com ghcr.io/redlink-gmbh/redlink-geocoding/geocoding-proxy-server\n```\nThe geocoding providers are autoconfigured using env-variables:\n* For Google provide an API-key using `GOOGLE_API_KEY`\n* For Nominatim, optionally provide `NOMINATIM_BASE_URL` and `NOMINATIM_MAIL`\n* For Caching configure the cache-ttl: `GEO_CACHE_SECONDS`\n\n### Proxy Client\n\nThe geocoding-proxy just needs to be configured with the base-url of the proxy-server:\n\n```java\nfinal Geocoder proxyGeocoder = ProxyGeocoder.builder()\n               .setBaseUri(\"http://localhost:8080/\")\n               .create();\n```\n\nMaven dependency:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.redlink.geocoding\u003c/groupId\u003e\n    \u003cartifactId\u003egeocoding-proxy\u003c/artifactId\u003e\n    \u003cversion\u003e${geocoding.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Spring-Boot Autoconfiguration\n\nFor quick and easy use of the `Geocoder` in [spring-boot] projects use the `geocoding-spring-boot-autoconfigure` module,\nand configure the geocoders with the following `application.properties`:\n\n```properties\n# GoogleMaps Geocoder\n## provide either api-key OR client-id and crypto-secret\ngeocoding.google.api-key=\ngeocoding.google.client-id=\ngeocoding.google.crypto-secret=\ngeocoding.google.channel=\n\n# Nominatim Geocoder\n## optional, defaults to public nominatim server by OSM\ngeocoding.nominatim.base-url=\ngeocoding.nominatim.email=\n## overriding endpoints is optional\ngeocoding.nominatim.endpoints.geocoding=/search\ngeocoding.nominatim.endpoints.reverse=/reverse\ngeocoding.nominatim.endpoints.lookup=/lookup\n## optional custom query params\ngeocoding.nominatim.extra-query-params.\u003ckey\u003e=\n## optional custom headers\ngeocoding.nominatim.extra-headers.\u003cheader-name\u003e=\n\n# Proxy Geocoder\ngeocoding.proxy-service.base-url=\n\n# General Options\ngeocoding.cache-timeout=\ngeocoding.lang=\ngeocoding.proxy=\n```\n\nMaven dependency:\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eio.redlink.geocoding\u003c/groupId\u003e\n        \u003cartifactId\u003egeocoding-spring-boot-autoconfigure\u003c/artifactId\u003e\n        \u003cversion\u003e${geocoding.version}\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003c!-- Add an implementation provider, at least one: --\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eio.redlink.geocoding\u003c/groupId\u003e\n        \u003cartifactId\u003egeocoding-google\u003c/artifactId\u003e\n        \u003cversion\u003e${geocoding.version}\u003c/version\u003e\n        \u003cscope\u003eruntime\u003c/scope\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eio.redlink.geocoding\u003c/groupId\u003e\n        \u003cartifactId\u003egeocoding-osm\u003c/artifactId\u003e\n        \u003cversion\u003e${geocoding.version}\u003c/version\u003e\n        \u003cscope\u003eruntime\u003c/scope\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eio.redlink.geocoding\u003c/groupId\u003e\n        \u003cartifactId\u003egeocoding-proxy\u003c/artifactId\u003e\n        \u003cversion\u003e${geocoding.version}\u003c/version\u003e\n        \u003cscope\u003eruntime\u003c/scope\u003e\n    \u003c/dependency\u003e\n    \u003c!-- optionally the chache --\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eio.redlink.geocoding\u003c/groupId\u003e\n        \u003cartifactId\u003egeocoding-cache\u003c/artifactId\u003e\n        \u003cversion\u003e${geocoding.version}\u003c/version\u003e\n        \u003cscope\u003eruntime\u003c/scope\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n## License\nFree use of this software is granted under the terms of the Apache License Version 2.0.\nSee the [License](LICENSE.txt) for more details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredlink-gmbh%2Fredlink-geocoding","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredlink-gmbh%2Fredlink-geocoding","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredlink-gmbh%2Fredlink-geocoding/lists"}