address-geocoder

A small npm CLI that prompts for an address, converts it to latitude/longitude using the free OpenStreetMap Nominatim API, and appends the result to a local file (JSON Lines format).

No API key and no dependencies required (uses Node's built-in fetch and readline).

Requirements

• Node.js 18+ (built-in fetch)

Usage

npm start
# or, if installed globally:
address-geocoder

You'll be prompted:

Enter an address: 1600 Amphitheatre Parkway, Mountain View, CA

Where results are saved

By default, results are appended to:

~/.address-geocoder/geocoded.json

This keeps the tool from writing into whatever directory you happen to run it in. You can control the location:

| Option | Description | | ------ | ----------- | | -o, --out <file> | Write results to a specific file (created if needed). | | ADDRESS_GEOCODER_OUT env var | Same as --out, but via the environment. | | --no-save | Print the result only; don't write any file. | | -h, --help | Show help. |

Precedence: --out > ADDRESS_GEOCODER_OUT > default home-dir path.

Examples

# Save to a custom file
address-geocoder --out ./locations.jsonl

# Set a persistent location via env var
export ADDRESS_GEOCODER_OUT=~/data/geo.jsonl
address-geocoder

# Just print, don't save
address-geocoder --no-save

Each saved line is one JSON object:

{"input":"...","latitude":37.42,"longitude":-122.08,"matched":"...","timestamp":"..."}

Notes

• Nominatim's usage policy asks for a descriptive User-Agent (already set) and a max of ~1 request/second. Please don't hammer it.