Whereabouts

Fast, scalable geocoding for Python using DuckDB. The geocoding algorithms are based on the following papers:

Description

Geocode addresses and reverse geocode coordinates directly from Python in your own environment.

No additional database setup required. Uses DuckDB to run all queries
No need to send data to an external geocoding API
Fast (Geocode 1000s / sec and reverse geocode 200,000s / sec)
Robust to typographical errors

Requirements

Python 3.8+
Poetry (for package management)

Installation

Once Poetry is installed and you are in the project directory:

poetry shell
poetry install

Create a geocoder database

To start geocoding, a geocoding database has to be created, which uses a reference dataset containing addresses and corresponding latitude, longitude values.

The reference file should be a single csv file with at least three fields: the complete address, latitude, longitude. These fields should be specified in a setup.yml file. An example is included.

Once the setup.yml is created and a reference dataset is available, the geocoding database can be created using the setup_geocoder function from whereabouts.utils.

The current process for using Australian data from the GNAF is as follows:

Download the latest version of GNAF core from https://geoscape.com.au/data/g-naf-core/
Update the setup.yml file to point to the location of the GNAF core file
Finally, setup the geocoder. This creates the required reference tables

python -m whereabouts setup_geocoder setup.yml

To use address data from another country, the file should have the following columns:

Column name	Description
ADDRESS_DETAIL_PID	Unique identifier for address
ADDRESS_LABEL	The full address
ADDRESS_SITE_NAME	Name of the site. This is usually null
LOCALITY_NAME	Name of the suburb or locality
POSTCODE	Postcode of address
STATE	State
LATITUDE	Latitude of geocoded address
LONGITUDE	Longitude of geocoded address

Examples

Geocode a list of addresses

from whereabouts.Matcher import Matcher

matcher = Matcher(db_name='gnaf_au')
matcher.geocode(addresslist, how='standard')

For more accurate geocoding you can use trigram phrases rather than token phrases (note that the trigram option has to have been specified in the setup.yml file as part of the setup)

matcher.geocode(addresslist, how='trigram')

Once a Matcher object is created, the KD-tree for fast geocoding will also be created. A list of latitude, longitude values can then be reverse geocoded as follows

matcher.reverse_geocode(coordinates)

Release files for whereabouts 0.3.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for whereabouts 0.3.4
File	Size	Uploaded
whereabouts-0.3.4.tar.gz	14.0 kB	Apr 7, 2024	Details

Built distribution (wheel)

Table of built distributions (wheels) for whereabouts 0.3.4
File	Interpreter	ABI	Platform	Reset
whereabouts-0.3.4-py3-none-any.whl 27.2 kB Apr 7, 2024	Python 3	none	any	Details

Total release size: 41.2 kB

Release files / whereabouts-0.3.4.tar.gz

Download URL	whereabouts-0.3.4.tar.gz
Size	14.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`8226930408c8c522dd3c78778533ce691eaea90f145ee9f44ba37e14a6f936fe`
BLAKE2b-256 checksum How to use checksums	`86d8231337bc4211c67d03b4300f535fac7b4fb5ada55691e326a54e7971d80a`
Upload date	Apr 7, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.7.1 CPython/3.12.2 Darwin/23.4.0`

Release files / whereabouts-0.3.4-py3-none-any.whl

Download URL	whereabouts-0.3.4-py3-none-any.whl
Size	27.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`9cabe4e918bc9bc3f5d2d62c267a340247c4490c2ab55cb986e6241f294f523f`
BLAKE2b-256 checksum How to use checksums	`16ab695419af124742edd2146961635caad2d23c79d27247ecdae92425aa8794`
Upload date	Apr 7, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.7.1 CPython/3.12.2 Darwin/23.4.0`