An on-premise version of the Geocodio API is available for enterprises.
The on-premise 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-premise 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.
For optimal performance, we recommended running Geocodio on a separate system that does not share resources with other applications.
Minimum hardware requirements:
After signing a Geocodio on-premise agreement, you will receive a username and passsword which is needed to access the Geocodio software and data files.
These credentials are specific to on-premise and cannot be used to access the Geocodio dashboard. You will receive separate dashboard access in order to access license keys.
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.
# 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
# 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
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 "<LICENSE KEY CONTENTS>" > /var/geocodio/license.key
Your license key is available from the Enterprise dashboard.
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 usually takes at least an hour. 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
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.7/geocode?q=1109+N+Highland+St%2c+Arlington+VA&api_key=YOUR_CHOICE_OF_API_KEY_VALUE"
Note: the Lists API is not available for on-premise, but you can use the batch geocoding endpoint to process CSVs of 10,000 or fewer rows each.
Updating Geocodio on-premise requires downloading a new release of the software and data archive. 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.
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.
It is possible to run Geocodio in "low memory mode" which reduces the memory allocation of the software.
Note: Enabling low memory mode disables support for rooftop-accuracy reverse geocoding. Reverse geocoding requests will still be available, but will use range-interpolated data. Forward geocoding is not affected.
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
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
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
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:
| HTTP Status Code | Description |
|---|---|
| 200 OK | Healthcheck is passing |
| 503 Service Unavailable | App is still booting |
| Any other status code | Healthcheck failed |
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