Utility for extracting OSM map data and converting it to TopoJSON
Last updated 2 years ago by tchayen .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install topojson-osm-fetch 
SYNC missed versions from official npm registry.


Node utilities for fetching data from Open Street Map and converting it to a TopoJSON file.

Check out the examples section for source code generating the map above


npm install -g topojson-osm-fetch

NOTE: Global install is not necessary if you want to use it only as a module

Usage as CLI

Download data

topofetch download b44.96,-93.3,45.0,-93.215 output.topojson

(prepend coordinates with b)

Output file is optional. Defaults to STDOUT.

Convert OSM to TopoJSON

If you have already downloaded OSM data as a JSON file

NOTE: it's not the same as GeoJSON, OSM also has JSON format for its XML-like data

topofetch convert -i map.json -o output.topojson

Both input and output files are optional. Input defaults to STDIN. Output defaults to STDOUT.

Usage as module

import { fetchData, convert } from 'topojson-osm-fetch'

const bounds = [50.0, 19.85, 50.105, 20.13].join()

convert(fetchData(bounds), console.log)


For API reference refer to index.js which contains JS Docs.


convert() takes configuration object as the third argument, which can look like this:

const defaultConfig = {
  output: {
    layers: {
        d =>,
        d =>,
        d => inArray(, ['unclassified', 'residential', 'pedestrian', 'living_street', 'road', 'tertiary', 'tertiary_link']),
        d => inArray(, ['trunk', 'trunk_link', 'primary', 'primary_link', 'secondary', 'secondary_link']),
        d => inArray(, ['motorway', 'motorway_link']),

The only thing needed for the layer is filter function used for separating it from others. d is data of a GeoJSON feature and comes from the OSM data that you provided.

The output TopoJSON file will have specified layers with their names.

NOTE: TopoJSON layers are simply properties of the features in the TopoJSON object


In order to comply with browsers' security restrictions, you probably must serve static content from local server.

This bash one-liner run from /examples directory comes to the rescue:

python -m SimpleHTTPServer 8000

d3.js SVG

The simplest use case is rendering a map via d3.js library. Sometimes it might be useful to keep the whole map as one asset file and render it as a whole.

Check out source code.


Fetching data

Fetching data from Open Street Map is based on Overpass API and its OverpassQL. It is really flexible and allows for querying quite complex relations between elements, but for now this lib uses only the following one:



out meta asc;
out skel qt;

where bounds is the provided bounds parameter.

As you can see there is whole lot of place for adding flexibility.


The OSM data is converted to GeoJSON and only then the final TopoJSON conversion takes place. It is also phase in which layer separation happens if specified in the config.

Future plans

  • handling edge cases (incorrect bounds, incorrect order of bounds, Overpass API error)
  • add query option for specifying own queries
  • add ability to somehow specify config from CLI
  • maybe custom QL over the (IMO messy) OverpassQL ????
  • maybe other tiny utility for generating preview image of downloaded data


The default query is far from satisfying all possible locations even for the style used in the examples (for example there is no easy way for showing seas as it works for rivers now).

Because of that, if you find any unhandled errors, improvement opportunities or have other ideas of any kind – feel free to submit pull request.

Current Tags

  • 0.0.7                                ...           latest (2 years ago)

7 Versions

  • 0.0.7                                ...           2 years ago
  • 0.0.6                                ...           2 years ago
  • 0.0.5                                ...           2 years ago
  • 0.0.4                                ...           2 years ago
  • 0.0.3                                ...           2 years ago
  • 0.0.2                                ...           2 years ago
  • 0.0.1                                ...           2 years ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 3
Dependencies (4)
Dev Dependencies (0)
Dependents (0)

Copyright 2014 - 2016 © |