Skip to main content

Open source geocoding in Python

Project description

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')

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

whereabouts-0.3.8.tar.gz (18.6 kB view details)

Uploaded Source

Built Distribution

whereabouts-0.3.8-py3-none-any.whl (33.7 kB view details)

Uploaded Python 3

File details

Details for the file whereabouts-0.3.8.tar.gz.

File metadata

  • Download URL: whereabouts-0.3.8.tar.gz
  • Upload date:
  • Size: 18.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.2 CPython/3.12.2 Darwin/23.5.0

File hashes

Hashes for whereabouts-0.3.8.tar.gz
Algorithm Hash digest
SHA256 077d8d1d2c300e6d91c8afba9db730a4a257267b5eedf3028aad6b54c37fafca
MD5 98194eaea518662dffaef52f950eede0
BLAKE2b-256 ad4611342bf4475903176077961a930026bfe350c70bec5c31189f8b721fedd6

See more details on using hashes here.

File details

Details for the file whereabouts-0.3.8-py3-none-any.whl.

File metadata

  • Download URL: whereabouts-0.3.8-py3-none-any.whl
  • Upload date:
  • Size: 33.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.2 CPython/3.12.2 Darwin/23.5.0

File hashes

Hashes for whereabouts-0.3.8-py3-none-any.whl
Algorithm Hash digest
SHA256 0358e34794a124f13b32315ad7cb436e4a8067fb58293b54fa57f8843d0b1c06
MD5 b49e90c5b73761cec44c31da9640fbaf
BLAKE2b-256 f11360bb467197d61e7e97347b52b2cff8395626ff2736b10dd0bab920ec11ec

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page