Macrocosm is a partial port of the Open Street Map Rails API in NodeJS
Branch: develop
Clone or download
Latest commit ce7a9e0 May 29, 2016
Type Name Latest commit message Commit time
Failed to load latest commit information.
.build_scripts Correct folder name. This is becoming embarrassing. Dec 8, 2015
db-server Add missing schema versions Dec 22, 2015
doc Test suite and documentation Dec 3, 2015
iD @ ae1c4c9
models Validate array using util Jan 8, 2016
routes Fix error type, confirm with test May 12, 2016
services Refactor error handling May 12, 2016
util Dedupe changeset tag insertion logic Jan 13, 2016
.dockerignore Add Docker configuration for local development and testing Dec 8, 2015
.eslintrc ESLint config Jan 20, 2016
.gitignore Ignore .swp files May 12, 2016
.gitmodules Changing submodule pull to non-auth method May 13, 2016
.nvmrc Reimplemented map endpoint to match cgimap queries Dec 31, 2015
.travis.yml Ignore submodules in travis May 13, 2016
Dockerfile Tell docker to use node 5.3 Jan 7, 2016 Adds GPL v2 Dec 7, 2015 Add caveat about iD in readme - not for production May 17, 2016 Starts off readme and includes basic roadmap Dec 4, 2015
apidoc.json Correct build command Dec 8, 2015
connection.js Fail fast if no connection is available Jan 20, 2016
docker-compose.yml Add Docker configuration for local development and testing Dec 8, 2015
index.js Cleaner HTTP debugging Jan 1, 2016
package.json Add changelog, increment version to 0.2.0 May 17, 2016


Build Status

Macrocosm is a partial port of the Open Street Map Ruby API in NodeJS. With Macrocosm, you can host your own version of the OSM platform. It comes bundled with a fork the iD editor that has been lightly modified to send data to a local Macrocosm API (more on that below). Macrocosm supports other data inputs, including direct uploads of OSM XML.

API docs are available here.

What's included

  1. Changeset creation and upload: create nodes, ways, relations, and their respective tags, using changesets to record metadata. Like in OSM, changesets record create, modify, and delete actions. Unlike OSM, there is no concept of closing changesets. They close after the last change is recorded.

  2. Bounding box queries: allow you to specify a bounding box (lat/lon) to get all the elements contained within.

  3. Bulk uploads: so you can populate an OSM-like database using OSM XML directly through the Macrocosm API.


Installing Macrocosm

git clone
cd macrocosm
npm install

Installing iD

git submodule update --init
cd iD

Local development using Docker

This repo comes with Docker configuration to spin up the API and a database. This same setup is also used by Travis to run tests against.

To set up your environment, make sure docker and docker-compose are installed on your machine. For Mac OS X and Windows download the Docker Toolbox. For Linux follow these instructions.

For Mac OS X or Windows, make sure you're running the following commands in a terminal that has the docker environment variables set. This can be done by running the Docker Quickstart Terminal app, or running eval $(docker-machine env default). Linux users may need to use sudo. Then start the database and API in the root directory of this repo:

npm run docker-start

Starting iD

To serve iD, start a web server in the iD subdirectory, eg. python -m SimpleHTTPServer.

You may need to change the url that iD posts changesets to, depending on your docker host ip address. To find this address, install Docker Machine and use docker-machine env:

$ docker-machine env default

^ In this case, you would change the url to // On Ubuntu, the API url will normally be localhost:4000.

Note The bundled version of iD is only lightly modified. It will post changesets to a local Macrocosm API instead of OpenStreetMap, but the rest of the code base is unchanged. As such, we recommend it's use for local development and testing only.

Running the database

You can also just spin up the database and make it available on $DOCKER_HOST:5433:

npm run docker-start-db # start the db
npm run docker-kill-db # kills the db

Running tests

The following command creates an empty postgres db, populates it with test data, and runs the tests against it.

npm run docker-test

Running the API

It is also possible to run the API without Docker. This is for example useful if you want to connect to an instance of the database hosted elsewhere.

Adapt the local.js file in your root directory that directs the API to a PostgreSQL database url (info on setting that up below). The placeholder contains the url for the database that Docker spins up.

module.exports.connection = {
    production: 'postgres://USER:PASSWORD@HOST:POST/DATABASE',

Now you can run the API using MACROCOSM_ENV=production npm run start.

Macrocosm allows you to specify different databases using environment variables, eg. if you have separate testing and production databases. To specify different databases, structure your local.js file as such:

module.exports.connection = {
    docker: 'postgres://osm:password@localhost:5432/macrocosm_test',
    production: 'postgres://USER:PASSWORD@HOST:POST/DATABASE',

Now you can run your tests on a separate database:

MACROCOSM_ENV=test npm run test

Building the documentation locally

npm run gendoc

On a push to master, Travis builds the documentation and pushes it to Github Pages. The .js and .json files that are built by npm run gendoc, should not be committed to Github.

Importing data

createdb macrocosm
psql -d macrocosm -f db-server/script/macrocosm-db.sql
osmosis \
  --read-pbf-fast delaware-latest.osm.pbf \
  --log-progress \
  --write-apidb database=macrocosm