A terminal interface built on top of @simple-nominatim/core for the Nominatim API.

It is part of the Simple Nominatim monorepo and is published on npm as @simple-nominatim/cli.

Disclaimers

The utilization of this project is governed by the Nominatim Usage Policy (aka Geocoding Policy). Please adhere to fair usage practices as outlined by the OSMF Operations Working Group.

The owner and contributors of the Simple Nominatim project, including its libraries, assume no responsibility for any misuse.

Installation

Simple Nominatim currently supports the Search, Reverse and Status endpoints.

npm install -g @simple-nominatim/cli

Requires Node.js >=24.10.0.

Usage

Top-level help:

simple-nominatim --help

Every subcommand also accepts --help to list its full option set.

reverse:geocode

simple-nominatim reverse:geocode --latitude '37.4219999' --longitude '-122.0840575' --format 'jsonv2'

• Required:
  • --latitude
  • --longitude
  • --format
• Optional:
  • --email
  • --zoom (0–18)
  • --addressdetails
  • --layer

search:free-form

simple-nominatim search:free-form --query 'Mountain View, CA, USA' --format 'jsonv2'

• Required:
  • --query
  • --format
• Optional:
  • --email
  • --limit (1–40)
  • --addressdetails
  • --countrycodes
  • --bounded
  • --viewbox
  • --layer
  • --feature-type

search:structured

simple-nominatim search:structured --country 'USA' --city 'Mountain View' --street '1600 Amphitheatre Parkway' --format 'jsonv2'

• Required:
  • --format
  • At least one component:
    • --amenity
    • --street
    • --city
    • --county
    • --state
    • --country
    • --postal-code
• Optional: same extras as search:free-form

search:free-form and search:structured cannot be combined — use one or the other.

status:service

simple-nominatim status:service --format 'json'

• Optional:
  • --format (text | json, default text)

Exit Codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Unknown / unclassified error | | 2 | CLI validation error (missing flag, bad type) | | 3 | HTTP error from Nominatim (4xx / 5xx, including 429) | | 4 | Network error (DNS, offline, socket) |

License

Simple Nominatim CLI is MIT licensed.