Registry / http-networking / osm-api

osm-api

JSON →
library4.0.0jsnpmunverified

The `osm-api` package provides a robust JavaScript/TypeScript wrapper for interacting with the OpenStreetMap API, designed for both Node.js (requiring Node.js >=18) and browser environments. Currently stable at version 4.0.0 (last published February 2026), the library facilitates common OSM operations such as fetching map features, managing changesets, user data, messaging, and notes. It automatically converts OSM's XML responses into JSON format, simplifying data handling for developers. A key differentiator is its use of OAuth 2 for authentication, enhancing security by avoiding the direct exposure of OAuth `client_secret`s. The library is lightweight (24 kB gzipped) and offers a simpler API and TypeScript support compared to older alternatives like `osm-request`. While a specific fixed release cadence is not explicitly stated, updates are released to address critical changes, such as the security patches to OSM's authentication flow, requiring timely library updates (e.g., v3.0.0 for a specific popup mode authentication fix).

npm install osm-api
INSTALL
IMPORT
SIG · OSM-API
O
osm-api
http-networkingjavascriptv4.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

OSM
import * as OSM from 'osm-api';
import OSM from 'osm-api';
The library exports a namespace, so use `* as OSM` for named imports. Direct default import is not supported.
OSM
const OSM = require('osm-api');
CommonJS require style for Node.js environments. This will import the entire module as a single object.
OSM (global)
<script src="https://unpkg.com/osm-api@4"></script>
import { getFeature } from 'osm-api';
For browser usage without a bundler, the library exposes a global `OSM` object. Individual functions are not directly exported for named import from the top level.

This quickstart demonstrates fetching a public OSM feature and outlines the pattern for authenticated API calls using OAuth 2, including necessary placeholders.

import * as OSM from 'osm-api'; async function runOsmApiExample() { try { // Public API call - no authentication required const feature = await OSM.getFeature('way', 23906749); console.log('Fetched feature:', feature); // Authenticated API calls require login first. // In a real application, replace these with your actual OAuth 2 client details // and handle the authentication flow (e.g., popup or redirect). // This is a placeholder for demonstration purposes. const authConfig = { client_id: process.env.OSM_CLIENT_ID ?? 'YOUR_CLIENT_ID', redirect_uri: process.env.OSM_REDIRECT_URI ?? 'YOUR_REDIRECT_URI', scope: 'write_changesets,write_notes', }; // This would typically involve a browser redirect or popup. // For a Node.js script, you'd likely manage tokens manually after an initial authorization step. // const authenticatedOSM = await OSM.login(authConfig); // console.log('Successfully attempted login (mock):', authenticatedOSM); // Example of an authenticated call (requires actual login to work) // Assuming an authenticated instance or global auth state after login // For this example, we'll simulate the call, but it won't work without actual auth. console.log('Attempting to create a changeset comment (requires authentication)...'); // const commentResult = await OSM.createChangesetComment(114733070, 'Thanks for your edit!'); // console.log('Changeset comment result:', commentResult); } catch (error) { console.error('An error occurred:', error.message); if (error.response) { console.error('OSM API Error details:', error.response.status, error.response.data); } } } runOsmApiExample();
Debug
Known issues
breakingAuthentication using the `popup` mode broke due to security changes on OpenStreetMap's side (effective July 8, 2025).
fix
Update `osm-api` to version 3.0.0 or higher. Additionally, update the code snippet in your `land.html` file to the latest version as per the popup documentation.
affects: <3.0.0
gotchaThe library requires Node.js version 18 or higher for server-side usage.
fix
Ensure your Node.js environment is updated to version 18 or newer. Use a version manager like `nvm` or `volta` to manage Node.js versions.
affects: >=1.0.0
gotchaOpenStreetMap's editing API has strict usage policies; clients may be blocked if they affect service levels or cause data corruption. Automated edits require community consultation.
fix
Familiarize yourself with the OSM API usage policy and guidelines for imports/automated edits. Consult the local community for significant automated operations.
affects: >=1.0.0
gotchaAuthentication via OAuth 2 requires careful handling of `client_id` and `redirect_uri`. Misconfiguration can lead to failed login attempts or security vulnerabilities.
fix
Ensure `client_id` and `redirect_uri` are correctly registered with OpenStreetMap and precisely match the values used in your application's `login` configuration. Never expose your `client_secret` in client-side code.
affects: >=1.0.0
gotchaOSM API requests, especially for large areas or complex queries, can occasionally result in server-side timeouts (e.g., 50x errors) or rate limiting due to high load on the volunteer-maintained OSM infrastructure.
fix
Implement robust error handling, retry mechanisms with exponential backoff, and consider caching strategies for read-only data. For heavy usage or large data needs, consider using Planet.osm data or commercial providers, or hosting your own tiles.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: OSM is not defined
Attempting to use `OSM` object in a browser environment without including the `<script>` tag, or trying to use CommonJS `require` in an ESM context without a proper bundler setup.
fix
For browsers, ensure `<script src="https://unpkg.com/osm-api@latest"></script>` is included before your script. For modern Node.js/bundled environments, use `import * as OSM from 'osm-api';`.
TypeError: (0 , osm_api_1.default) is not a function
Attempting to use `import OSM from 'osm-api';` when the library primarily exports a namespace (`* as OSM`) rather than a default export.
fix
Change your import statement to `import * as OSM from 'osm-api';` to correctly import the namespace.
Error: "Authentication failed: popup mode requires library update and land.html modification."
Attempting to use the `popup` authentication mode with an outdated `osm-api` library version (prior to v3.0.0) or without updating the `land.html` snippet after recent OSM security changes.
fix
Upgrade `osm-api` to version 3.0.0 or newer via `npm install osm-api@latest` and ensure your `land.html` file includes the latest required code snippet for popup authentication.
HTTP Error 401 Unauthorized
Attempting an authenticated API call without successfully logging in or with expired/invalid OAuth credentials (e.g., wrong `client_id`, `redirect_uri`, or scope).
fix
Verify your OAuth 2 `client_id`, `redirect_uri`, and requested `scope` are correct and that the user has successfully completed the authentication flow and granted necessary permissions. Ensure your tokens are fresh if managing them manually.
Upgrade
Version history
4.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
14 hits · last 30 days
node
12
OpenAI (training)
1
Resources
osm-api — npm install osm-api · libregistry