https://github.com/ethlo/geodata

API-driven fast and free geo-data server for flexible deployment. Comes with a pre-built Docker image.
https://github.com/ethlo/geodata

docker geonames gis ip2country ip2location iplookup

Last synced: 6 months ago
JSON representation

API-driven fast and free geo-data server for flexible deployment. Comes with a pre-built Docker image.

• Host: GitHub
• URL: https://github.com/ethlo/geodata
• Owner: ethlo
• Created: 2017-05-15T05:33:55.000Z (about 9 years ago)
• Default Branch: main
• Last Pushed: 2025-05-30T08:31:42.000Z (about 1 year ago)
• Last Synced: 2025-10-23T06:33:22.459Z (10 months ago)
• Topics: docker, geonames, gis, ip2country, ip2location, iplookup
• Language: Java
• Homepage:
• Size: 6.16 MB
• Stars: 1
• Watchers: 1
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# Geodata

![Docker Image Version (latest semver)](https://img.shields.io/docker/v/ethlocom/geodata-server?sort=semver)

![Docker Image Size (latest by date)](https://img.shields.io/docker/image-size/ethlocom/geodata-server)

![Docker Pulls](https://img.shields.io/docker/pulls/ethlocom/geodata-server)

![Splash info page](docs/img/splash.jpg?raw=true)

### Features

Simple, fast and free geo-data server for flexible deployment. This service is intended for doing quick lookups, like:

* Searching for a location by name, ip, telephone number, lat/long coordinates

* Query if a location is a child, grand-child, etc of another location

* Browse location hierarchy (starting from continents and moving down administrative locations)

NOTE: This is not an advanced GIS tool for map manipulation and analysis.

### Performance

Low memory overhead and super-fast response times utilizing appropriate fit-for-purpose data-structures, and a highly optimized HTTP handler built on UnderTow. Depending on hardware you can expect thousands to hundreds-of-thousands of requests per second.

### Ease-of-use

For quick and easy distribution of data the system utilizes no database. Typical data imports are a few hundred mega bytes, 

and require no further processing or data-loading before running on a server.

### Fully documented RESTful API

The API is fully documented using Open API 3.x specification and allows for easy consumption from numerous platforms.

![OpenAPI docs](docs/img/openapi.jpg?raw=true)

## Usage guide

### Import and process data

Prerequisite: You need to register for an account at MaxMind (free) for the GeoLite2 data

Simple, sample script I use for creating data-set for the server:

```shell script

docker run --memory=2G --rm --name geodata-server-import \

-v ~/geodata/data:/geodata-server/data \

-v ~/geodata/input:/geodata-server/input \

-v /tmp/geodata:/tmp/geodata \

-e "GEODATA_IMPORT=1" \

-e "GEODATA_MAXDATAAGE=P14D" \

-e "GEODATA_GEOLITE2_LICENSE_KEY=<>" ethlocom/geodata-server

```

### Start the server

Start the server and load the data from the import step. Listen on host port 6566. 

```shell script

docker run -d --rm -m1G -p 6566:6565 --name geodata-server -v ~/geodata/data:/geodata-server/data \

-e JAVA_OPTS="-XX:MaxDirectMemorySize=1G" ethlocom/geodata-server:latest \ 

&& docker logs -f geodata-server

```

## This service utilize data from:

- Geonames.org - Free data is available under [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/) license

- This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.