{"id":16475,"library":"osm-api","title":"OpenStreetMap API for JavaScript/TypeScript","description":"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).","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/osmlab/osm-api-js","tags":["javascript","osm","openstreetmap","openstreetmap api","typescript"],"install":[{"cmd":"npm install osm-api","lang":"bash","label":"npm"},{"cmd":"yarn add osm-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add osm-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library exports a namespace, so use `* as OSM` for named imports. Direct default import is not supported.","wrong":"import OSM from 'osm-api';","symbol":"OSM","correct":"import * as OSM from 'osm-api';"},{"note":"CommonJS require style for Node.js environments. This will import the entire module as a single object.","symbol":"OSM","correct":"const OSM = require('osm-api');"},{"note":"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.","wrong":"import { getFeature } from 'osm-api';","symbol":"OSM (global)","correct":"<script src=\"https://unpkg.com/osm-api@4\"></script>"}],"quickstart":{"code":"import * as OSM from 'osm-api';\n\nasync function runOsmApiExample() {\n  try {\n    // Public API call - no authentication required\n    const feature = await OSM.getFeature('way', 23906749);\n    console.log('Fetched feature:', feature);\n\n    // Authenticated API calls require login first.\n    // In a real application, replace these with your actual OAuth 2 client details\n    // and handle the authentication flow (e.g., popup or redirect).\n    // This is a placeholder for demonstration purposes.\n    const authConfig = {\n      client_id: process.env.OSM_CLIENT_ID ?? 'YOUR_CLIENT_ID',\n      redirect_uri: process.env.OSM_REDIRECT_URI ?? 'YOUR_REDIRECT_URI',\n      scope: 'write_changesets,write_notes',\n    };\n    \n    // This would typically involve a browser redirect or popup.\n    // For a Node.js script, you'd likely manage tokens manually after an initial authorization step.\n    // const authenticatedOSM = await OSM.login(authConfig);\n    // console.log('Successfully attempted login (mock):', authenticatedOSM);\n\n    // Example of an authenticated call (requires actual login to work)\n    // Assuming an authenticated instance or global auth state after login\n    // For this example, we'll simulate the call, but it won't work without actual auth.\n    console.log('Attempting to create a changeset comment (requires authentication)...');\n    // const commentResult = await OSM.createChangesetComment(114733070, 'Thanks for your edit!');\n    // console.log('Changeset comment result:', commentResult);\n\n  } catch (error) {\n    console.error('An error occurred:', error.message);\n    if (error.response) {\n      console.error('OSM API Error details:', error.response.status, error.response.data);\n    }\n  }\n}\n\nrunOsmApiExample();","lang":"typescript","description":"This quickstart demonstrates fetching a public OSM feature and outlines the pattern for authenticated API calls using OAuth 2, including necessary placeholders."},"warnings":[{"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.","message":"Authentication using the `popup` mode broke due to security changes on OpenStreetMap's side (effective July 8, 2025).","severity":"breaking","affected_versions":"<3.0.0"},{"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.","message":"The library requires Node.js version 18 or higher for server-side usage.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Familiarize yourself with the OSM API usage policy and guidelines for imports/automated edits. Consult the local community for significant automated operations.","message":"OpenStreetMap'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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Authentication via OAuth 2 requires careful handling of `client_id` and `redirect_uri`. Misconfiguration can lead to failed login attempts or security vulnerabilities.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"OSM 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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';`.","cause":"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.","error":"ReferenceError: OSM is not defined"},{"fix":"Change your import statement to `import * as OSM from 'osm-api';` to correctly import the namespace.","cause":"Attempting to use `import OSM from 'osm-api';` when the library primarily exports a namespace (`* as OSM`) rather than a default export.","error":"TypeError: (0 , osm_api_1.default) is not a function"},{"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.","cause":"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.","error":"Error: \"Authentication failed: popup mode requires library update and land.html modification.\""},{"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.","cause":"Attempting an authenticated API call without successfully logging in or with expired/invalid OAuth credentials (e.g., wrong `client_id`, `redirect_uri`, or scope).","error":"HTTP Error 401 Unauthorized"}],"ecosystem":"npm"}