#csv #geocoding #column #file #bulk #smarty #city

app geocode-csv

CLI tool to bulk geocode CSV data using the Smarty API or libpostal

23 releases (stable)

1.4.0 Mar 26, 2024
1.3.12 Aug 26, 2023
1.3.7 May 22, 2023
1.3.0 Jun 29, 2022
0.2.0 Nov 19, 2019

#32 in Geospatial

Download history 24/week @ 2024-02-26 5/week @ 2024-03-11 123/week @ 2024-03-25 133/week @ 2024-04-01

261 downloads per month

Apache-2.0 OR MIT

3.5K SLoC

geocode-csv: Geocode a CSV file using libpostal or the Smarty API

(This project is not associated with Smarty.)

WARNING: This project geocodes CSV files thousands of rows per second, which can use up your Smarty quota very quickly. This may cost you money.

If you have a CSV file that appears as follows:

Resident,1600 Pennsylvania Avenue NW,,Washington DC,20500

...and an address_spec.json file that appears as follows:

  "geocoded": {
    "street": ["street1", "street2"],
    "city": "city",
    "state": "state",
    "zipcode": "zip"

...then you can geocode it using:

# Set up credentials.
export SMARTY_AUTH_ID=...

# Geocode the CSV.
geocode-csv --spec address_spec.json < in.csv > out.csv

This will add a series of columns starting with geocoded_, which will contain various postal delivery information, plus estimated latitude and longitude. If geocoding succeeds, geocode-csv will return 0. If it fails, it will return a non-zero error code and print a human-readable error message to standard error.

You can geocode multiple addresses per row as follows:

  "geocoded_shipping": {
    /* ... */
  "geocoded_billing": {
    /* ... */

This will insert two sets of columns, one beginning with geocoded_shipping_ and the other with geocoded_billing_.


You'll need to run:

git submodule update --init

...to pull in the C++ source for libpostal.

You will also need to install protoc:

# Linux.
sudo apt install protobuf-compiler

# Mac.
brew install protobuf

A note about Macs

We provide pre-built Mac binaries for Intel- and M1-based Macs. These binaries use "ad-hoc" signatures, so you may need to set appropriate security settings or run:

xattr -d com.apple.quarantine geocode-csv


~1.5M SLoC