A small ESM library that wraps the Nominatim API with typed request helpers.

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

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 @simple-nominatim/core

Requires Node.js >=24.10.0.

Usage

Each helper takes a params object (endpoint-specific) and an options object (shared query parameters). Both accept an optional baseUrl and userAgent to target a self-hosted Nominatim instance or identify the caller.

Reverse — geocodeReverse

import { geocodeReverse } from "@simple-nominatim/core";

const result = await geocodeReverse(
  { latitude: "37.4219999", longitude: "-122.0840575" },
  { format: "jsonv2" },
);

• Required params:
  • latitude, longitude (WGS84)
• Required options:
  • format (xml | json | jsonv2 | geojson | geocodejson)
• Common options:
  • email
  • zoom (0–18)
  • addressdetails
  • layer

Search — freeFormSearch

import { freeFormSearch } from "@simple-nominatim/core";

const results = await freeFormSearch(
  { query: "1600 Amphitheatre Parkway, Mountain View, CA, USA" },
  { format: "jsonv2" },
);

• Required params:
  • query
• Common options:
  • email
  • format
  • limit (1–40)
  • addressdetails
  • countrycodes
  • bounded
  • viewbox
  • layer
  • featureType

Search — structuredSearch

import { structuredSearch } from "@simple-nominatim/core";

const results = await structuredSearch(
  { country: "USA", city: "Mountain View", street: "1600 Amphitheatre Parkway" },
  { format: "jsonv2" },
);

• Params (all optional, at least one required):
  • amenity
  • street
  • city
  • county
  • state
  • country
  • postalCode
• Options: same as freeFormSearch

Status — serviceStatus

import { serviceStatus, isStatusSuccess } from "@simple-nominatim/core";

const status = await serviceStatus({ format: "json" });

if (typeof status !== "string" && isStatusSuccess(status)) {
  console.log(status.software_version);
}

• Options:
  • format (text | json, default text)
• Text format: returns the string "OK" on success; throws on failure.
• JSON format: returns StatusSuccessResponse (status: 0) or StatusErrorResponse (status: 700+).

Error Handling

All helpers throw typed errors that you can narrow with isRequestError:

import { freeFormSearch, isRequestError, HttpRequestError, NetworkRequestError } from "@simple-nominatim/core";

try {
  await freeFormSearch({ query: "Paris" }, { format: "json" });
} catch (error) {
  if (error instanceof HttpRequestError) {
    // error.status, error.statusText
  } else if (error instanceof NetworkRequestError) {
    // DNS / offline / socket issue
  } else if (isRequestError(error)) {
    // any RequestError subclass
  }
}

License

Simple Nominatim Core is MIT licensed.