@geocodeearth/ge

Geocode Earth command-line tools

Usage no npm install needed!

<script type="module">
  import geocodeearthGe from 'https://cdn.skypack.dev/@geocodeearth/ge';
</script>

README

[BETA] This repo is still a work-in-progress.

Installation

npm i -g @geocodeearth/ge

CLI

ge <cmd> [args]

Commands:
  ge batch  batch geocoding tools

Options:
      --version  Show version number                                   [boolean]
  -v, --verbose  enable verbose logging               [boolean] [default: false]
      --help     Show help                                             [boolean]

Authentication

In order to authenticate with the Geocode Earth servers you must have a valid API key from Geocode Earth. You can sign up for a free key at https://geocode.earth/ or visit https://app.geocode.earth/dashboard to find an existing key.

You must export your API key in your shell so it is available as an environment variable:

export GE_API_KEY=ge-xxxxxxxxxxxxxxxx

You can check that it's been set correctly with the env command.

Batch CSV Geocoding

ge batch csv <file>

append geocoded columns to a CSV file

Positionals:
  file  location of the input CSV file.                      [string] [required]

Options:
      --version      Show version number                               [boolean]
  -v, --verbose      enable verbose logging           [boolean] [default: false]
      --help         Show help                                         [boolean]
  -p, --param        Define a parameter.                                [string]
  -t, --template     Define a template.                                 [string]
      --endpoint     API endpoint to query.     [string] [default: "/v1/search"]
      --concurrency  Maximim queries per-second.           [number] [default: 5]
Preparing the CSV file

Your input CSV must contain a header row on the first line with column names. Please ensure that the file is valid before continuing.

Working with streams

The basic usage is ge batch csv <file> where <file> can be either a file or a stream.

You can accept a CSV on stdin as such:

cat input.csv | ge batch csv /dev/stdin

and capture the updated CSV on stdout as such:

cat input.csv | ge batch csv /dev/stdin | xsv table
Debugging

You can increase the verbosity for debugging purposes. Logs are written to stderr:

ge batch csv \
  --verbose
Parameter templating

The basic usage is ge batch csv <file>, but this alone will not yeild results. You'll first need to define a mapping from the field names in your CSV to HTTP request parameters which will be sent to Geocode Earth.

This can be achieved using a pair of flags, -p to name the parameter and -t to define a template for the parameter value.

For example the following will set the querystring parameter text to equal 1 Main Street, London, assuming that the CSV contains columns named number, street and city:

ge batch csv \
  -p 'text' \
  -t '${row.number} ${row.street}, ${row.city}'

We use the lodash template engine and pass it a single variable row which contains the data for the current row in the CSV file.

You can add multiple pairs of parameters, please take care to match each -p with a -t.

note: be careful to use single-quotes ' instead of double-quotes " on the command-line to avoid your shell interpolating the string.

Search Example
ge batch csv \
  --endpoint '/v1/search' \
  -p 'text' -t '${row.NUMBER} ${row.STREET}, ${row.CITY}' \
  -p 'boundary.country' -t 'NZ' \
  /data/oa/nz/countrywide.csv
Structured Search Example
ge batch csv \
  --endpoint '/v1/search/structured' \
  -p 'address' -t '${row.NUMBER} ${row.STREET}' \
  -p 'city' -t '${row.CITY}' \
  -p 'boundary.country' -t 'NZ' \
  /data/oa/nz/countrywide.csv
Reverse Example
ge batch csv \
  --endpoint '/v1/reverse' \
  -p 'point.lat' -t '${row.LAT}' \
  -p 'point.lon' -t '${row.LON}' \
  /data/oa/nz/countrywide.csv
Autocomplete Example
ge batch csv \
  --endpoint '/v1/autocomplete' \
  -p 'text' -t '${row.NUMBER} ${row.STREET}, ${row.CITY}' \
  -p 'focus.point.lat' -t '${row.LAT}' \
  -p 'focus.point.lon' -t '${row.LON}' \
  -p 'boundary.country' -t 'NZ' \
  /data/oa/nz/countrywide.csv