OpenStreetMap API for Javascript

!npm bundle size

🗺️🌏 Javascript/Typescript wrapper around the OpenStreetMap API.

> [!IMPORTANT]
> Due to security changes on 8 July 2025, authentication using the popup mode will not work until you:
>
> 1. update this library to v3.0.0
> 2. AND update the code snippet in your land.html file to the latest version (see the popup documentation below)

Benefits:

- Lightweight (24 kB gzipped)
- works in nodejs and the browser.
- converts OSM's XML into JSON automatically.
- uses OAuth 2, so that you don't need to expose your OAuth client_secret

Install

``sh
npm install osm-api
`

Usage

`js
const OSM = require("osm-api");
// or
import * as OSM from "osm-api";

// you can call methods that don't require authentication
await OSM.getFeature("way", 23906749);

// Once you login, you can call methods that require authentication.
// See the section below about authentication.
await OSM.createChangesetComment(114733070, "Thanks for your edit!");
`

If you don't use a bundler, you can also include the module using a

`

Examples

All methods return promises. Examples requests and responses are available for all methods:

> 🔑 means the method requires authentication

- Features
- getFeature()
- getFeatures()
- getFeatureAtVersion
- getFeatureHistory
- getWaysForNode
- getRelationsForElement
- Changesets
- listChangesets
- getChangeset
- getChangesetDiff
- getChangesetComments
- 🔑 uploadChangeset
- 🔑 createChangesetComment
- 🔑 subscribeToChangeset()
- 🔑 unsubscribeFromChangeset()
- Users
- getUser
- getUsers
- getUIdFromDisplayName
- getUserBlockById
- 🔑 getOwnUserBlocks
- Messaging
- 🔑 deleteMessage()
- 🔑 getMessage()
- 🔑 listMessages()
- 🔑 sendMessage()
- 🔑 updateMessageReadStatus()
- Notes
- getNotesForQuery()
- getNotesForArea()
- createNote()
- 🔑 closeNote()
- 🔑 commentOnNote()
- 🔑 reopenNote()
- 🔑 subscribeToNote()
- 🔑 unsubscribeFromNote()
- Preferences
- 🔑 getPreferences()
- 🔑 updatePreferences()
- 🔑 deletePreferences()
- Misc
- getApiCapabilities()
- getMapData
- Using the Development Server
- Additional type-safety for Keys/Tags
- DWG-only APIs
- Authentication (browser only, not available in NodeJS)
- login
- logout
- isLoggedIn
- 🔑 getAuthToken()
- authReady
- getPermissions()

Authentication in the browser

When used in the browser, this library lets you authenticate to OSM using OAuth 2. This requires either:

1. Redirecting the user to the OAuth page, or
2. Opening a popup window.

$3

If using a popup, you should create a separate landing page, such as land.html. This html file should contain the following code:

> 💡 If you don't want to create a separate page, you can set the redirect URL to your
> app's main page, as long as you include this HTML snippet.

`html

`

To login, or check whether the user is logged in, use the following code:

`js
const OSM = require("osm-api");

OSM.login({
mode: "popup",
clientId: ".......",
redirectUrl: "https://example.com/land.html",
// see the type definitions for other options
})
.then(() => {
console.log("User is now logged in!");
})
.catch(() => {
console.log("User cancelled the login, or there was an error");
});

// you can check if a user is logged in using
OSM.isLoggedIn();

// and you can get the access_token using
OSM.getAuthToken();
`

$3

If you use the redirect method, you don't need a separate landing page.

`js
const OSM = require("osm-api");

// when you call this function, you will be immediately redirected to openstreetmap.org
OSM.login({
mode: "redirect",
clientId: ".......",
redirectUrl: "https://example.com/land.html",
// see the type definitions for other options
});
`

`js
const OSM = require("osm-api");

// If you login using the redirect method, you need to await
// this promise before you can call isLoggedIn or getAuthToken.
await OSM.authReady;

// you can check if a user is logged in using
OSM.isLoggedIn();

// and you can get the access_token using
OSM.getAuthToken();
`

Authentication in NodeJS

In NodeJS, if you want to use a method that requires authentication, call the configure() function first:

`js
const OSM = require("osm-api");

OSM.configure({ authHeader: Bearer ${authToken} });
// or
OSM.configure({ basicAuth: { username: "...", password: "..." } });

// now you can call methods that require authentication.
// Example:
await OSM.createChangesetComment(114733070, "Thanks for your edit!");
``

Comparison with osm-request

This library offers several advantages over osm-request:

1. TypeScript support: osm-api-js is built with TypeScript, providing better type safety and developer experience.
2. Simpler API: The API is designed to be more straightforward and easier to use.
3. Smaller bundle size: With fewer dependencies, osm-api-js has a noticeably smaller bundle size.

While osm-request has been revived, osm-api-js was created when osm-request was abandoned and lacked OAuth 2 support.