Demozoo geocoder
================

A place name lookup API based on the geonames.org dataset.

We made our own because all the existing lookup services are rubbish. This one's fairly rubbish too, but at least it won't get shut down by Google or Yahoo to maximise shareholder value.


API endpoints
-------------

* Search: http://geocoder.demozoo.org/?q=lutjebroek
* Show: http://geocoder.demozoo.org/2751379/


Tech breakdown
--------------

In use, this is a simple Django app backed by a sqlite database (1.4Gb in size as of November 2020). Since it's stateless and read-only, this makes it easy to package up in a self-contained way for cloud hosting platforms, without having to worry about persistent storage or database connections.

The database is built using a set of Django management commands which download the data files from geonames.org (approx 500Mb) and load them into the database. This takes about 4Gb of memory and 2-3 hours to complete. I don't recommend doing it in a VM - that just makes it needlessly slow.

Installation
------------

To build the database, run the following from a clean Python 3.x virtualenv:

    make data

Or if you absolutely insist on using a VM:

    vagrant up
    vagrant ssh
    cd geocoder
    make data


Acceptable use policy
---------------------

Don't be a dick, and then I won't have to waste my time locking it down with API keys and rate limiting and that sort of rubbish.


Matt Westcott <matt@west.co.tt> - https://twitter.com/gasmanic