README.md

OpenStreetMap API for Javascript

🗺️🌏 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

npm install osm-api

Usage

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 <script> tag:

<script src="https://unpkg.com/osm-api@2"></script>
<script>
  OSM.getFeature("way", 23906749);
  OSM.login({ ... });
  ...
</script>

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.

1. Popup

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.

<script>
  if (new URLSearchParams(location.search).has("code")) {
    new BroadcastChannel("osm-api-auth-complete").postMessage(location.href);
    window.close();
  }
</script>

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

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();

2. Redirect

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

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
});

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:

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.