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+
- requirements.txt (found in repo)
Installation: via PIP
whereabouts can be installed either from this repo using pip / uv / conda
pip install whereabouts
1. Install depedencies
Install all the dependencies:
pip install -r requirements.txt
Download a geocoder database or create your own
You will need a geocoding database to match addresses against. You can either download a pre-built database or create your own using a dataset of high quality reference addresses for a given country, state or other geographic region.
1. Download a geocoder database
Pre-built geocoding database are available from Huggingface. The list of available databases can be found here
As an example, to install the small size geocoder database for all of Australia:
python -m whereabouts download au_all_sm
2. Create a geocoder database
You can create your own geocoder database if you have your own address file. This file should be a single csv or parquet file with the following columns:
| Column name | Description | Data type |
|---|---|---|
| ADDRESS_DETAIL_PID | Unique identifier for address | int |
| ADDRESS_LABEL | The full address | str |
| ADDRESS_SITE_NAME | Name of the site. This is usually null | str |
| LOCALITY_NAME | Name of the suburb or locality | str |
| POSTCODE | Postcode of address | int |
| STATE | State | str |
| LATITUDE | Latitude of geocoded address | float |
| LONGITUDE | Longitude of geocoded address | float |
These fields should be specified in a setup.yml file. Once the setup.yml is created and a reference dataset is available, the geocoding database can be created:
python -m whereabouts setup_geocoder setup.yml
Geocoding 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')
1 maintainer
Release files for whereabouts 0.3.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| whereabouts-0.3.8.tar.gz | 18.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| whereabouts-0.3.8-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 52.4 kB
Release files / whereabouts-0.3.8.tar.gz
| Download URL | whereabouts-0.3.8.tar.gz |
|---|---|
| Size | 18.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
077d8d1d2c300e6d91c8afba9db730a4a257267b5eedf3028aad6b54c37fafca
|
|
BLAKE2b-256 checksum How to use checksums |
ad4611342bf4475903176077961a930026bfe350c70bec5c31189f8b721fedd6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.2 CPython/3.12.2 Darwin/23.5.0
|
Release files / whereabouts-0.3.8-py3-none-any.whl
| Download URL | whereabouts-0.3.8-py3-none-any.whl |
|---|---|
| Size | 33.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0358e34794a124f13b32315ad7cb436e4a8067fb58293b54fa57f8843d0b1c06
|
|
BLAKE2b-256 checksum How to use checksums |
f11360bb467197d61e7e97347b52b2cff8395626ff2736b10dd0bab920ec11ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.2 CPython/3.12.2 Darwin/23.5.0
|
