hyperdb-osm-server
Peer-to-peer OpenStreetMap API v0.6 Server
An implementation of the OpenStreetMap API v0.6 for hyperdb-osm
, a peer-to-peer OSM database. It runs on node.js or, if you are creative, also in the browser. Data is stored in a LevelUP database. There is no need to set up a database, everything you need to get started is available as a single package that you can install from npm.
hyperdb-osm-server
is tested and working with iD Editor - it appears as identical to the standard OSM API. It should theoretically work in the future with other editors such as JOSM but hyperdb-osm-server
needs to use at least 64-bit ids to avoid collisions, and JOSM currently still uses 32-bit integers for some ids, such as changeset ids and version numbers.
hyperdb-osm-server
is designed to run locally on each client. Synchronize data between clients by replicating the hyperdb-osm
database. You can implement replication over wifi, bluetooth or via USB thumb drives (examples coming soon).
This module is for developers who want to build their own OSM tools. For users who want a one-click install of hyperdb-osm-server
with iD Editor see Mapeo Desktop.
Table of Contents
Install
You will need to first install node.js
npm install hyperdb-osm-server
Routes
hyperdb-osm-server
currently implements the following routes from the OSM API v0.6:
-
GET /api(/0.6)?/capabilities
-
GET /api/0.6/map
-
PUT /api/0.6/changeset/create
-
POST /api/0.6/changeset/:id/upload
-
PUT /api/0.6/changeset/:id/close
-
GET /api/0.6/map
-
GET /api/0.6/:type(nodes|ways|relations)?:ktype(nodes|ways|relations)=:ids
-
GET /api/0.6/:type(node|way|relation)/:id
-
GET /api/0.6/:type(node|way|relation)/:id/:version
-
GET /api/0.6/:type(node|way|relation)/:id
-
GET /api/0.6/:type(node|way|relation)/:id/history
-
GET /api/0.6/:type(way|relation)/:id/full
API
var osmrouter =
var router = osmrouter(osm)
Create a new OpenStreetMap router
given an
hyperdb-osm
handle osm
.
var m = router.handle(req, res)
Match the req.method
and req.url
and dispatch m.fn(m, req, res)
and return
the match object if there is a match, or else null
.
var m = router.match(method, url)
Return a match object m
if method
and url
can be handled by the server.
Used internally by router.handle()
.
The match object for router.match('GET', '/api/0.6/node/1234')
would be:
params: type: 'node' id: '1234' splats: route: '/:type(node|way|relation)/:id' fn: Function next: Function
API Example
var hyperosm = var hyperdb = var ram = var memdb = var Geo = var osmRouter = var osm = var router = var http = var server = httpserver
Use as Express middleware
var hyperosm = var hyperdb = var ram = var memdb = var Geo = var osmRouter = var express = var osm = var app = app app app
REST API
See the documentation for the OSM API v0.6 - hyperdb-osm-server
replicates that API as faithfully as possible.
Differences to OSM API v0.6
The main differences to the OSM API v0.6 are related to the peer-to-peer architecture of hyperdb-osm-server
. Ids are randomly generated, rather than sequential integers. Version ids are hashes rather than integers. For more details read hyperdb-osm
Architecture.
-
If two users edit the same version of an entity (node|way|relation) then two versions will exist in the database.
hyperdb-osm-server
will not return409: Conflict
if you try to modify or delete an entity which is not the most recent version, it will create a fork instead. Forks can be created if two users edit the same entity whilst disconnected and then later replicate the database. -
By default
hyperdb-osm-server
will only return the most recent 'fork', to maintain compatibility with tools that do not understand the concept of forked entities. To see all forks, append?forks=true
to the URL and if multiple forks exist the returned data will include multiple entities with the sameid
, but differentversion
ids. -
In changeset uploads (
/changeset/:id/upload
), theversion
property of each entity in the changeset can be a comma-separated list of version hashes of the documents that the update will replace. Use this to merge multiple forks into a single fork.
Contributing
If something does not work as it should, please open an Issue. Pull Requests are welcome, please follow JS Standard Style.