From 232c053bd2bfd94dbd22c1309aec5602bc391728 Mon Sep 17 00:00:00 2001 From: RayBB Date: Tue, 10 Sep 2024 14:02:31 +0200 Subject: [PATCH 1/4] add docs on using the development server --- README.md | 1 + examples/useDevServer.md | 15 +++++++++++++++ 2 files changed, 16 insertions(+) create mode 100644 examples/useDevServer.md diff --git a/README.md b/README.md index 3ede9e6..99d2984 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,7 @@ All methods return promises. Examples requests and responses are available for a - Misc - [`getCapabilities()`](./examples/getCapabilities.md) - [`getMapData`](./examples/getMapData.md) + - [`Using the Development Server`](./examples/useDevServer.md) - Authentication (browser only, not available in NodeJS) - `login` - `logout` diff --git a/examples/useDevServer.md b/examples/useDevServer.md new file mode 100644 index 0000000..e94fd90 --- /dev/null +++ b/examples/useDevServer.md @@ -0,0 +1,15 @@ +# Using the Development Server + +For testing and experimenting with the API, use the development server documented [here](https://wiki.openstreetmap.org/wiki/API_v0.6). It uses a separate database with less data, allowing you to test freely without concerns. + +1. Create an account and application key on the [development server](https://master.apis.dev.openstreetmap.org/oauth2/applications). + +2. Configure the library to use the development server: + +``` ts +OSM.configure({ apiUrl: "https://master.apis.dev.openstreetmap.org" }) +``` + +With configure you can also change the user agent and other options as seen in [config.ts](../src/config.ts). + +Now you're ready to start making requests to the development server! From 5f66c27f8754b5e23ed1f5f226ae706614ef178d Mon Sep 17 00:00:00 2001 From: RayBB Date: Tue, 10 Sep 2024 14:21:35 +0200 Subject: [PATCH 2/4] add more examples to uploadChangeset --- examples/uploadChangeset.md | 55 +++++++++++++++++++++++++++++++++++++ examples/useDevServer.md | 2 +- 2 files changed, 56 insertions(+), 1 deletion(-) diff --git a/examples/uploadChangeset.md b/examples/uploadChangeset.md index cc6f3ad..9235996 100644 --- a/examples/uploadChangeset.md +++ b/examples/uploadChangeset.md @@ -27,3 +27,58 @@ Response: ``` (changeset number) + +## Updating existing features + +```ts + +import { getFeature } from "osm-api"; +const id = 12345; +const type = "node"; + +const featureResponse = await getFeature(type, id); +if (featureResponse.length > 0) { + const feature = featureResponse[0]; + if (feature.tags) { + feature.tags["amenity"] = "restaurant"; + } else { + feature.tags = { "amenity": "restaurant" }; + } + await uploadChangeset( + { + created_by: "id", + comment: "tagging as resturant", + }, + { + create: [], + modify: [feature], + delete: [], + }); +} +``` + +## Creating new features +To create a new node, several of the fields will have be be blanked out +```ts +import { OsmNode } from "osm-api"; + +const lat = 123.456; +const lon = 789.123; +const tags = { + "amenity": "restaurant", +}; + +const newNode: OsmNode = { + type: "node", + lat: lat, + lon: lon, + tags: tags, + id: -1, // Negative ID for new nodes + changeset: -1, + timestamp: '', + uid: -1, + user: '', + version: 0, +}; +``` +Then you can add it to the changeset `create: [newNode]` as above. diff --git a/examples/useDevServer.md b/examples/useDevServer.md index e94fd90..b79983e 100644 --- a/examples/useDevServer.md +++ b/examples/useDevServer.md @@ -1,6 +1,6 @@ # Using the Development Server -For testing and experimenting with the API, use the development server documented [here](https://wiki.openstreetmap.org/wiki/API_v0.6). It uses a separate database with less data, allowing you to test freely without concerns. +For experimenting with the API, use the development server documented [here](https://wiki.openstreetmap.org/wiki/API_v0.6). It uses a separate database with less data, allowing you to test freely without concerns. 1. Create an account and application key on the [development server](https://master.apis.dev.openstreetmap.org/oauth2/applications). From 99aa46e3c4988548bc0b649b3bd75e35f779376b Mon Sep 17 00:00:00 2001 From: RayBB Date: Tue, 10 Sep 2024 14:35:42 +0200 Subject: [PATCH 3/4] update readme with comparison to osm-request --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 99d2984..2f04dcb 100644 --- a/README.md +++ b/README.md @@ -172,3 +172,13 @@ OSM.configure({ basicAuth: { username: "...", password: "..." } }); // Example: await OSM.createChangesetComment(114733070, "Thanks for your edit!"); ``` + +## Comparison with osm-request + +This library offers several advantages over [osm-request](https://github.com/osmlab/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. From cf62eb221a6f36ce256d421ddb7642285c3652b9 Mon Sep 17 00:00:00 2001 From: Kyle Hensel Date: Mon, 16 Sep 2024 19:00:24 +1000 Subject: [PATCH 4/4] copyediting --- README.md | 2 +- examples/{useDevServer.md => dev-server.md} | 9 ++- examples/uploadChangeset.md | 68 +++++++++------------ 3 files changed, 35 insertions(+), 44 deletions(-) rename examples/{useDevServer.md => dev-server.md} (60%) diff --git a/README.md b/README.md index 2f04dcb..c6c5377 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ All methods return promises. Examples requests and responses are available for a - Misc - [`getCapabilities()`](./examples/getCapabilities.md) - [`getMapData`](./examples/getMapData.md) - - [`Using the Development Server`](./examples/useDevServer.md) + - [Using the Development Server](./examples/dev-server.md) - Authentication (browser only, not available in NodeJS) - `login` - `logout` diff --git a/examples/useDevServer.md b/examples/dev-server.md similarity index 60% rename from examples/useDevServer.md rename to examples/dev-server.md index b79983e..3626165 100644 --- a/examples/useDevServer.md +++ b/examples/dev-server.md @@ -1,15 +1,14 @@ # Using the Development Server -For experimenting with the API, use the development server documented [here](https://wiki.openstreetmap.org/wiki/API_v0.6). It uses a separate database with less data, allowing you to test freely without concerns. +For experimenting with the API, use the development server documented [here](https://osm.wiki/API_v0.6#URL_+_authentication). +It uses a separate database with less data, allowing you to test without affecting the real database. 1. Create an account and application key on the [development server](https://master.apis.dev.openstreetmap.org/oauth2/applications). 2. Configure the library to use the development server: -``` ts -OSM.configure({ apiUrl: "https://master.apis.dev.openstreetmap.org" }) +```ts +OSM.configure({ apiUrl: "https://master.apis.dev.openstreetmap.org" }); ``` -With configure you can also change the user agent and other options as seen in [config.ts](../src/config.ts). - Now you're ready to start making requests to the development server! diff --git a/examples/uploadChangeset.md b/examples/uploadChangeset.md index 9235996..a3ba8b0 100644 --- a/examples/uploadChangeset.md +++ b/examples/uploadChangeset.md @@ -28,57 +28,49 @@ Response: (changeset number) -## Updating existing features +## Detailed Examples -```ts +### Updating existing features +```ts import { getFeature } from "osm-api"; -const id = 12345; -const type = "node"; - -const featureResponse = await getFeature(type, id); -if (featureResponse.length > 0) { - const feature = featureResponse[0]; - if (feature.tags) { - feature.tags["amenity"] = "restaurant"; - } else { - feature.tags = { "amenity": "restaurant" }; - } - await uploadChangeset( - { - created_by: "id", - comment: "tagging as resturant", - }, - { - create: [], - modify: [feature], - delete: [], - }); -} + +const [feature] = await getFeature("node", 12345); + +feature.tags ||= {}; +feature.tags.amenity = "restaurant"; + +await uploadChangeset( + { created_by: "MyApp 1.0", comment: "tagging as resturant" }, + { create: [], modify: [feature], delete: [] } +); ``` -## Creating new features +### Creating new features + To create a new node, several of the fields will have be be blanked out + ```ts import { OsmNode } from "osm-api"; -const lat = 123.456; -const lon = 789.123; -const tags = { - "amenity": "restaurant", -}; - const newNode: OsmNode = { type: "node", - lat: lat, - lon: lon, - tags: tags, - id: -1, // Negative ID for new nodes + lat: 123.456, + lon: 789.123, + tags: { + amenity: "restaurant", + }, + id: -1, // Negative ID for new features + changeset: -1, - timestamp: '', + timestamp: "", uid: -1, - user: '', + user: "", version: 0, }; + +await uploadChangeset( + { created_by: "MyApp 1.0", comment: "tagging as resturant" }, + { create: [newNode], modify: [], delete: [] } +); ``` -Then you can add it to the changeset `create: [newNode]` as above.