A self-hostable REST-like API to get the time zone from geo coordinates
Geo2Tz
A self-host-able service to get the timezone given geo-coordinates (lat/long)
It does it by exposing the library from github.com/evanoberholster/timezoneLookup
Timezone data comes from github.com/evansiroky/timezone-boundary-builder (release 2023b)
Motivations
Geo-coordinates might be sensitive information to share in any context, and I needed a self-hosted solution to ensure that coordinates were not leaked to 3rd party services. On another side, this feature is nicely self-contained and having one service to expose it spares the effort to bundle the TZ database everywhere.
API
the service exposes only one API:
GET /tz/${LATITUDE}/${LONGITUDE}
that returns a JSON reply (http/200
), for example:
curl -s http://localhost:2004/tz/51.477811/0 | jq
{ "coords": { "lat": 51.47781, "lon": 0 }, "tz": "Europe/London" }
or in case of errors (http/4**
), for example:
curl -v http://localhost:2004/tz/51.477811/1000 | jq
{ "message": "lon value 1000 out of range (-180/+180)" }Authorization
Geo2Tz supports a basic token authorization mechanism, if the configuration value for web.auth_token_value
is a non-empty string, geo2tz will check the query parameter value to authorize incoming requests.
For example, running the service with:
docker run -p 2004:2004 -e GEO2TZ_WEB_AUTH_TOKEN_VALUE=secret noandrea/geo2tz
will enable authorization. With the authorization enabled, a query that does not specify the token will fail with an HTTP code 401:
> curl -sv http://localhost:2004/tz/41.902782/12.496365 | jq
* Trying 127.0.0.1:2004...
Passing the token in the query parameters will succeed instead:
> curl -s http://localhost:2004/tz/41.902782/12.496365\?t\=secret | jq
{ "coords": { "lat": 41.902782, "lon": 12.496365 }, "tz": "Europe/Rome" }Docker
Docker image is available at geo2tzt
docker run -p 2004:2004 github.com/noandrea/geo2tz
The image is built on scratch, the image size is ~92MB:
Docker composeDocker compose YAML example
version: '3' services: geo2tz: container_name: geo2tz image: github.com/noandrea/geo2tz ports:
Kubernetes configuration example:
--- # Deployment apiVersion: extensions/v1beta1 kind: Deployment metadata: labels: app: geo2tz name: geo2tz spec: replicas: 1 revisionHistoryLimit: 3 selector: matchLabels: app: geo2tz template: metadata: labels: app: geo2tz spec: containers:
To update the timezone database, set the version of the database in the scripts/update-tzdata.sh
script and run:
make update-tzdata
Twice a month we will interview people behind open source businesses. We will talk about how they are building a business on top of open source projects.
We'll never share your email with anyone else.