@pepo2405/nominatim

Typed, headless wrapper around the Nominatim (OpenStreetMap) geocoding Search API.

• Zero runtime dependencies. Uses the global fetch, so it runs in Node 18+, browsers, React Native, Bun and Deno.
• No UI. Just geocode(address) → coordinates. Bring your own map / debounce / state.
• Typed. Normalizes Nominatim's string lat/lon into numbers.

Install

bun add @pepo2405/nominatim
# or: npm i @pepo2405/nominatim

Usage

import { geocode } from "@pepo2405/nominatim";

const results = await geocode("Av. Corrientes 1000, CABA", {
  userAgent: "my-app/1.0", // required by the public OSM server's usage policy
  limit: 5,
  language: "es",
});

// results: { placeId, displayName, lat, lon }[]  (lat/lon are numbers)

Options

| Option | Type | Default | Notes | | ----------- | ------------- | ------------------------------------ | ----- | | baseUrl | string | https://nominatim.openstreetmap.org| Point it at a self-hosted Nominatim instance. | | userAgent | string | — | Sent where the platform allows it (server / React Native); browsers ignore it and send Referer. | | limit | number | 5 | Max results. | | language | string | — | Accept-Language header, e.g. "es". | | signal | AbortSignal | — | Cancel in-flight requests (autocomplete). |

• Queries shorter than 3 characters return [] without a network call.
• A non-OK HTTP response throws GeocodeError (with .status).
• An aborted request rejects with the underlying AbortError, so you can tell cancellation apart from a real failure.

Usage policy

The public OSM server is rate-limited (~1 req/s, User-Agent required, autocomplete discouraged). For heavier or as-you-type use, self-host Nominatim and set baseUrl. See the usage policy.

Develop

bun install
bun test
bun run build   # tsup → ESM + CJS + .d.ts in dist/

License

MIT