An on-premises version of the Geocodio API is available for enterprises.

The on-premises Geocodio software is available as a Docker image and it can run on any host system where Docker is supported.

It does not require external internet access and can therefore run completely private and isolated on your own infrastructure.

The Geocodio dashboard (including spreadsheet uploads and usage tracking) is not available for on-premises installations. In addition, the Lists API is also unavailable, but it does support batch geocoding CSV files of less than 10,000 rows each via the batch geocoding endpoint.

On this page

exclude: On this page
# This code block gets replaced with the TOC

Requirements

For optimal performance, we recommended running Geocodio on a separate system that does not share resources with other applications.

Hardware recommendations:

• CPU: 6+ CPU cores

• Memory: 64GB memory

• Disk: 800B NVMe disk (Disk read speeds of 3,000 MB/s+ are recommended)

AWS EC2 instance

If using AWS, we recommend the following configuration:

Instance type: r5.2xlarge (8 vCPUs, 64 GB memory)

Storage configuration:

• Root volume: 800 GB gp3 EBS volume

• IOPS: 5000

• Throughput: 125 MB/s

Network configuration:

• Place in a private subnet if only internal access is needed

• Use security groups to restrict access to port 80 (or your custom port)

• Consider using an Application Load Balancer for SSL termination and high availability

Credentials

After signing a Geocodio on-premises agreement, you will receive a username and password which is needed to access the Geocodio software and data files.

These credentials are specific to on-premises and cannot be used to access the Geocodio dashboard. You will receive separate dashboard access in order to access license keys.

Running Geocodio Software

Download

In an internet-connected environment, you need to download the Geocodio software as well as a data archive.

The Geocodio Docker image is distributed in two versions: the standard version and an unprivileged version where the container runs as a non-root user.

If in doubt, we recommend using the standard version.

# Standard Docker image
wget --user=your_username --ask-password https://releases.geocod.io/geocodio-docker.tar.gz

# Alternative: Unprivileged Docker image
wget --user=your_username --ask-password https://releases.geocod.io/geocodio-docker-unprivileged.tar.gz

The data archive is also distributed in two versions. Most customers will want to use the full data archive. The lite data archive is significantly smaller in size as it does not include U.S. Census and ACS data appends.

# Full data archive
wget --user=your_username --ask-password https://releases.geocod.io/geocodio-data-full.tar.gz

# Alternative: Lite data archive that does not include U.S. Census and ACS data appends
wget --user=your_username --ask-password https://releases.geocod.io/geocodio-data-lite.tar.gz

After the files have been downloaded, you can transfer them to the host server using your prefered method.

You can also download these files directly from your host server if it is not in an air-gapped environment.

Prepare host server (standard version)

# Load docker image
docker load < geocodio-docker.tar.gz

# Prepare data directory and move geocodio-data-full.tar.gz there
mkdir /var/geocodio
mv geocodio-data-full.tar.gz /var/geocodio

Prepare host server (unprivileged version)

# Load docker image
docker load < geocodio-docker-unprivileged.tar.gz

# Prepare data directory and move geocodio-data-full.tar.gz there
mkdir /var/geocodio
mv geocodio-data-full.tar.gz /var/geocodio

# The Geocodio Docker container needs to be able to access /var/geocodio with UID 1001
chown -R 1001:1001 /var/geocodio

Apply license key

The license key is required to run your Geocodio installation. It needs to be placed in the /var/geocodio folder in order to be read by the software.

echo "" > /var/geocodio/license.key

Your license key is available from the Enterprise dashboard.

Run container

Run the Docker container by using the Docker image that was loaded in the previous step. A volume is necessary to load the data archive.

An environment variable is set to specify the API key that should be used for your Geocodio installation. The API key can be set to any alphanumeric string without spaces.

If openssl is available, you can generate a random API key value like so:

export GEOCODIO_API_KEY=$(openssl rand -base64 32 | tr -d "=+/")
echo $GEOCODIO_API_KEY

export GEOCODIO_API_KEY="YOUR_CHOICE_OF_API_KEY_VALUE"
docker run -d -p 80:80 --volume=/var/geocodio:/data --name geocodio -e GEOCODIO_API_KEY geocodio:latest

# or if using the unprivileged version:
# docker run -d -p 80:80 --volume=/var/geocodio:/data --name geocodio -e GEOCODIO_API_KEY geocodio-unprivileged:latest

The first time the container is started, it will take a while before the software is available as the data archive is being extracted and prepared. This process typically takes 60-90 minutes on recommended hardware. This may be a good time to grab a cup of coffee. ☕

You can check the status of this process by tailing its logs:

docker logs -f geocodio

Access the Geocodio API

You will now be able to access the API using the same endpoints as described in the Geocodio Docs.

curl "http://YOUR_SERVER_IP_ADDRESS/v1.9/geocode?q=1109+N+Highland+St%2c+Arlington+VA&api_key=YOUR_CHOICE_OF_API_KEY_VALUE"

Validate installation

After the container is running, validate that all services are working correctly:

# Test forward geocoding
curl "http://YOUR_SERVER_IP_ADDRESS/v1.9/geocode?q=1109+N+Highland+St%2c+Arlington+VA&api_key=YOUR_CHOICE_OF_API_KEY_VALUE"

# Test reverse geocoding
curl "http://YOUR_SERVER_IP_ADDRESS/v1.9/reverse?q=38.886672,-77.094735&api_key=YOUR_CHOICE_OF_API_KEY_VALUE"

# Verify health check returns 200 OK
curl -I http://YOUR_SERVER_IP_ADDRESS/healthcheck

Updating Geocodio software

Geocodio releases quarterly updates with new software and data. Updating requires downloading a new release of both the software and data archive (versions must match). You can follow the same process as with installation.

The Geocodio API is completely stateless and the Docker container does not store any permanent information or settings. As a result, you can replace the Docker image and data archive and delete previous data entirely.

The update process typically takes 60-90 minutes on recommended hardware, similar to initial installation.

Advanced usage

SSL

Geocodio does not ship with SSL support built-in. We recommend using a reverse proxy for SSL terminaton, ssuch as jwilder/nginx-proxy , optionally paired with jrcs/letsencrypt-nginx-proxy-companion.

Low memory mode

It is possible to run Geocodio in "low memory mode" which reduces the memory allocation of the software.

This mode can be enabled to let Geocodio run on hardware with as little as 2GB available memory.

To enable, set the LOW_MEMORY_MODE environment variable to true, like so:

docker run -d -p 80:80 --volume=/var/geocodio:/data --name geocodio -e GEOCODIO_API_KEY -e LOW_MEMORY_MODE=true geocodio:latest

Custom internal timeout

The Geocodio software has internal timeouts in place to protect against excessively long response times. The standard internal timeout would never be exceeded under normal operations on hardware fulfilling the minimum requirements.

While not recommended, it may however be desirable to run the software on less powerful hardware and allowing geocoding requests to take longer. This can be done by increasing the DEFAULT_QUERY_TIMEOUT_MS environment variable. The current default value is 2500 milliseconds.

To change this, set the DEFAULT_QUERY_TIMEOUT_MS environment variable to a desired value, like so:

docker run -d -p 80:80 --volume=/var/geocodio:/data --name geocodio -e GEOCODIO_API_KEY -e DEFAULT_QUERY_TIMEOUT_MS=10000 geocodio:latest

Custom HTTP port

Geocodio listens on port 80 per default. It is possible to overwrite the default port using the APP_PORT environment variable.

docker run -d -p 8888:8888 --volume=/var/geocodio:/data --name geocodio -e GEOCODIO_API_KEY -e APP_PORT=8888 geocodio:latest

Health check

If a health check is needed (for example, for an upstream loadbalancer), the following URL can be used:

curl -s -o /dev/null -w "%{http_code}" http://YOUR_SERVER_IP_ADDRESS/healthcheck

Monitor the HTTP status code to determine the health status of the service:

Faster startup time for additional instances

To decrease startup time for additional instances, it is possible to copy the prepared data directory from an existing Geocodio software instance to a new one.

This can be done as follows:

# Stop currently running Geocodio container to prevent file corruption
docker stop geocodio

# Use your preferred method to copy the data directory
scp -r /var/geocodio some-other-instance-ip-address:/var/geocodio

# Start the Geocodio container again
docker start geocodio

Security best practices

• API key management: Store your API key as an environment variable rather than hardcoding it in scripts

• Network isolation: If the API only needs to be accessible internally, restrict container network access

• Firewall configuration: Only expose necessary ports (typically just port 80 or your custom port)

Troubleshooting

Container won't start

• Check Docker daemon is running: docker info

• Verify license.key exists in /var/geocodio/: ls -la /var/geocodio/license.key

• Check available disk space (needs ~200GB during extraction): df -h

• Review container logs: docker logs geocodio

License invalid errors

• Verify license.key file location: must be in /var/geocodio/license.key

• Check file permissions (especially for unprivileged version)

• Ensure license.key contents are complete (no truncation)

API returns 503 Service Unavailable

• Container is still extracting data on first run (60-90 minutes)

• Check container status: docker ps

• Review logs for errors: docker logs geocodio

Environment variables reference