{"id":27230537,"url":"https://github.com/osmlab/osm-api-js","last_synced_at":"2025-07-19T10:33:56.039Z","repository":{"id":42532470,"uuid":"440392534","full_name":"osmlab/osm-api-js","owner":"osmlab","description":"🗺️🌏 Javascript/Typescript wrapper around the OpenStreetMap API","archived":false,"fork":false,"pushed_at":"2025-06-25T08:59:41.000Z","size":777,"stargazers_count":27,"open_issues_count":4,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-03T13:54:39.683Z","etag":null,"topics":["openstreetmap","osm"],"latest_commit_sha":null,"homepage":"https://npm.im/osm-api","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osmlab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-12-21T04:45:16.000Z","updated_at":"2025-06-25T08:59:44.000Z","dependencies_parsed_at":"2024-01-30T06:52:49.711Z","dependency_job_id":"4cc9ff4f-95aa-40db-ad2a-e054a3a98308","html_url":"https://github.com/osmlab/osm-api-js","commit_stats":{"total_commits":13,"total_committers":2,"mean_commits":6.5,"dds":0.3076923076923077,"last_synced_commit":"8df1cf8b4afcf6f542cf539adcd87f289b9a24b3"},"previous_names":["osmlab/osm-api-js","k-yle/osm-api-js"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/osmlab/osm-api-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmlab%2Fosm-api-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmlab%2Fosm-api-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmlab%2Fosm-api-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmlab%2Fosm-api-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osmlab","download_url":"https://codeload.github.com/osmlab/osm-api-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmlab%2Fosm-api-js/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265916934,"owners_count":23848822,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openstreetmap","osm"],"created_at":"2025-04-10T13:12:56.279Z","updated_at":"2025-07-19T10:33:56.012Z","avatar_url":"https://github.com/osmlab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenStreetMap API for Javascript\n\n[![Build Status](https://github.com/osmlab/osm-api-js/workflows/Build%20and%20Test/badge.svg)](https://github.com/osmlab/osm-api-js/actions)\n[![Coverage Status](https://coveralls.io/repos/github/osmlab/osm-api-js/badge.svg?branch=main\u0026t=LQmPNl)](https://coveralls.io/github/osmlab/osm-api-js?branch=main)\n[![npm version](https://badge.fury.io/js/osm-api.svg)](https://badge.fury.io/js/osm-api)\n[![npm](https://img.shields.io/npm/dt/osm-api.svg)](https://www.npmjs.com/package/osm-api)\n![npm bundle size](https://img.shields.io/bundlephobia/minzip/osm-api)\n\n🗺️🌏 Javascript/Typescript wrapper around the OpenStreetMap API.\n\n\u003e [!IMPORTANT]\n\u003e Due to [security changes on 8 July 2025](https://github.com/openstreetmap/openstreetmap-website/commit/2ff4d6), authentication using the `popup` mode will not work until you:\n\u003e\n\u003e 1. update this library to v3.0.0\n\u003e 2. AND update the code snippet in your `land.html` file to the latest version (see [the popup documentation below](#1-popup))\n\nBenefits:\n\n- Lightweight (24 kB gzipped)\n- works in nodejs and the browser.\n- converts OSM's XML into JSON automatically.\n- uses OAuth 2, so that you don't need to expose your OAuth `client_secret`\n\n## Install\n\n```sh\nnpm install osm-api\n```\n\n## Usage\n\n```js\nconst OSM = require(\"osm-api\");\n// or\nimport * as OSM from \"osm-api\";\n\n// you can call methods that don't require authentication\nawait OSM.getFeature(\"way\", 23906749);\n\n// Once you login, you can call methods that require authentication.\n// See the section below about authentication.\nawait OSM.createChangesetComment(114733070, \"Thanks for your edit!\");\n```\n\nIf you don't use a bundler, you can also include the module using a `\u003cscript\u003e` tag:\n\n```html\n\u003cscript src=\"https://unpkg.com/osm-api@2\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  OSM.getFeature(\"way\", 23906749);\n  OSM.login({ ... });\n  ...\n\u003c/script\u003e\n```\n\n## Examples\n\nAll methods return promises. Examples requests and responses are available for all methods:\n\n\u003e 🔑 means the method requires authentication\n\n- Features\n  - [`getFeature()`](./examples/getFeature.md)\n  - [`getFeatures()`](./examples/getFeatures.md)\n  - [`getFeatureAtVersion`](./examples/getFeatureAtVersion.md)\n  - [`getFeatureHistory`](./examples/getFeatureHistory.md)\n  - [`getWaysForNode`](./examples/getWaysForNode.md)\n  - [`getRelationsForElement`](./examples/getRelationsForElement.md)\n- Changesets\n  - [`listChangesets`](./examples/listChangesets.md)\n  - [`getChangeset`](./examples/getChangeset.md)\n  - [`getChangesetDiff`](./examples/getChangesetDiff.md)\n  - 🔑 [`uploadChangeset`](./examples/uploadChangeset.md)\n  - 🔑 [`createChangesetComment`](./examples/createChangesetComment.md)\n  - 🔑 [`subscribeToChangeset()`](./examples/subscribeToChangeset.md)\n  - 🔑 [`unsubscribeFromChangeset()`](./examples/unsubscribeFromChangeset.md)\n- Users\n  - [`getUser`](./examples/getUser.md)\n  - [`getUsers`](./examples/getUsers.md)\n  - [`getUIdFromDisplayName`](./examples/getUIdFromDisplayName.md)\n  - [`getUserBlockById`](./examples/getUserBlockById.md)\n  - 🔑 [`getOwnUserBlocks`](./examples/getOwnUserBlocks.md)\n- Messaging\n  - 🔑 [`deleteMessage()`](./examples/deleteMessage.md)\n  - 🔑 [`getMessage()`](./examples/getMessage.md)\n  - 🔑 [`listMessages()`](./examples/listMessages.md)\n  - 🔑 [`sendMessage()`](./examples/sendMessage.md)\n  - 🔑 [`updateMessageReadStatus()`](./examples/updateMessageReadStatus.md)\n- Notes\n  - [`getNotesForQuery()`](./examples/getNotesForQuery.md)\n  - [`getNotesForArea()`](./examples/getNotesForArea.md)\n  - [`createNote()`](./examples/createNote.md)\n  - 🔑 [`commentOnNote()`](./examples/commentOnNote.md)\n  - 🔑 [`reopenNote()`](./examples/reopenNote.md)\n  - 🔑 [`subscribeToNote()`](./examples/subscribeToNote.md)\n  - 🔑 [`unsubscribeFromNote()`](./examples/unsubscribeFromNote.md)\n- Preferences\n  - 🔑 [`getPreferences()`](./examples/getPreferences.md)\n  - 🔑 [`updatePreferences()`](./examples/updatePreferences.md)\n  - 🔑 [`deletePreferences()`](./examples/deletePreferences.md)\n- Misc\n  - [`getApiCapabilities()`](./examples/getApiCapabilities.md)\n  - [`getMapData`](./examples/getMapData.md)\n  - [Using the Development Server](./examples/dev-server.md)\n  - [Additional type-safety for Keys/Tags](./examples/type-safe-tags.md)\n- Authentication (browser only, not available in NodeJS)\n  - `login`\n  - `logout`\n  - `isLoggedIn`\n  - 🔑 `getAuthToken()`\n  - `authReady`\n  - [`getPermissions()`](./examples/getPermissions.md)\n\n## Authentication in the browser\n\nWhen used in the browser, this library lets you authenticate to OSM using OAuth 2. This requires either:\n\n1. Redirecting the user to the OAuth page, or\n2. Opening a popup window.\n\n### 1. Popup\n\nIf using a popup, you should create a separate landing page, such as `land.html`. This html file should contain the following code:\n\n\u003e 💡 If you don't want to create a separate page, you can set the redirect URL to your\n\u003e app's main page, as long as you include this HTML snippet.\n\n```html\n\u003cscript\u003e\n  if (new URLSearchParams(location.search).has(\"code\")) {\n    new BroadcastChannel(\"osm-api-auth-complete\").postMessage(location.href);\n    window.close();\n  }\n\u003c/script\u003e\n```\n\nTo login, or check whether the user is logged in, use the following code:\n\n```js\nconst OSM = require(\"osm-api\");\n\nOSM.login({\n  mode: \"popup\",\n  clientId: \".......\",\n  redirectUrl: \"https://example.com/land.html\",\n  // see the type definitions for other options\n})\n  .then(() =\u003e {\n    console.log(\"User is now logged in!\");\n  })\n  .catch(() =\u003e {\n    console.log(\"User cancelled the login, or there was an error\");\n  });\n\n// you can check if a user is logged in using\nOSM.isLoggedIn();\n\n// and you can get the access_token using\nOSM.getAuthToken();\n```\n\n### 2. Redirect\n\nIf you use the redirect method, you don't need a separate landing page.\n\n```js\nconst OSM = require(\"osm-api\");\n\n// when you call this function, you will be immediately redirected to openstreetmap.org\nOSM.login({\n  mode: \"redirect\",\n  clientId: \".......\",\n  redirectUrl: \"https://example.com/land.html\",\n  // see the type definitions for other options\n});\n```\n\n```js\nconst OSM = require(\"osm-api\");\n\n// If you login using the redirect method, you need to await\n// this promise before you can call `isLoggedIn` or `getAuthToken`.\nawait OSM.authReady;\n\n// you can check if a user is logged in using\nOSM.isLoggedIn();\n\n// and you can get the access_token using\nOSM.getAuthToken();\n```\n\n## Authentication in NodeJS\n\nIn NodeJS, if you want to use a method that requires authentication, call the `configure()` function first:\n\n```js\nconst OSM = require(\"osm-api\");\n\nOSM.configure({ authHeader: `Bearer ${authToken}` });\n// or\nOSM.configure({ basicAuth: { username: \"...\", password: \"...\" } });\n\n// now you can call methods that require authentication.\n// Example:\nawait OSM.createChangesetComment(114733070, \"Thanks for your edit!\");\n```\n\n## Comparison with osm-request\n\nThis library offers several advantages over [osm-request](https://github.com/osmlab/osm-request):\n\n1. **TypeScript support**: osm-api-js is built with TypeScript, providing better type safety and developer experience.\n2. **Simpler API**: The API is designed to be more straightforward and easier to use.\n3. **Smaller bundle size**: With fewer dependencies, osm-api-js has a noticeably smaller bundle size.\n\nWhile osm-request has been revived, osm-api-js was created when osm-request was abandoned and lacked OAuth 2 support.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosmlab%2Fosm-api-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosmlab%2Fosm-api-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosmlab%2Fosm-api-js/lists"}