osmtogeojson

To use osmtogeojson within a Node.js project, install it as a dependency and require it in your script.

Installation

$ npm install osmtogeojson

Usage

var osmtogeojson = require('osmtogeojson');
osmtogeojson(osm_data);

You can include osmtogeojson in your web application by adding the script tag to your HTML.

Usage

<script src='osmtogeojson.js'></script>

<script>
  osmtogeojson(osm_data);
</script>

The osmtogeojson function automatically detects the input format and uses the appropriate internal conversion logic:

1. OSM XML: Detected if the data is an instance of XMLDocument or has childNodes. It uses _osmXML2geoJSON to parse the XML structure.
2. Overpass JSON: Detected if the input is not an XML document. It uses _overpassJSON2geoJSON to parse the JSON structure.

Both paths eventually converge on a common _convert2geoJSON logic to build the final GeoJSON structure.

By default, osmtogeojson produces a nested properties structure containing type, id, tags, relations, and meta. If you set options.flatProperties to true, the properties are merged into a single flat object. The resulting structure for each feature will be:

"properties": {
  "type": "...",
  "id": "type/id",
  "tag_key_1": "value1",
  "tag_key_2": "value2",
  ... 
}

This is useful for simplifying the data for consumption by tools that expect a flat attribute list.

The osmtogeojson command-line tool converts OpenStreetMap (OSM) data in various formats (XML, JSON, PBF) into GeoJSON. You can provide a file path as an argument or pipe data directly into the command via stdin.

Basic Usage

osmtogeojson input.osm > output.geojson

Supported Input Formats

The tool automatically detects the format from the file extension, but you can specify it manually using the -f flag. Supported formats include:

• osm (or xml): OpenStreetMap XML files.
• json: OpenStreetMap JSON files.
• pbf: OpenStreetMap PBF binary files.
• auto: Automatic detection (default).

If no file is provided, the tool reads from stdin.

The core function converts OSM data into a GeoJSON FeatureCollection.

Parameters:

• data: The OSM data. This can be an XML DOM or OSM JSON.
• options (optional): An object to configure the conversion.

Options:

• flatProperties: (boolean, default: false) If true, the resulting GeoJSON feature's properties will be a simple key-value list instead of a structured JSON object containing tags and meta.
• uninterestingTags: A blacklist of tag keys or a callback function used to decide if a feature is "interesting" enough to be included as a GeoJSON feature.
• polygonFeatures: A JSON object or callback function used to determine if a closed way should be treated as a Polygon or LineString.

To control how OSM ways are classified as Polygon vs LineString, use the polygonFeatures option.

Using a function:

const options = {
  polygonFeatures: (tags) => {
    return tags.building === 'yes' || tags.highway === 'residential';
  }
};

Using a configuration object:

const options = {
  polygonFeatures: {
    building: true, // Any way with a 'building' tag is a polygon
    highway: {
      included_values: { residential: true, service: true }
    },
    natural: {
      excluded_values: { water: true }
    }
  }
};

By default, the CLI outputs a single GeoJSON FeatureCollection. If you need to process features one by one (e.g., for streaming or large datasets), use the --ndjson flag. This will output each feature as a single line of JSON, delimited by newlines. Note that using --ndjson automatically enables the minification (-m) flag.

osmtogeojson --ndjson input.osm > output.ndjson

You can install osmtogeojson globally via npm to convert OSM XML files to GeoJSON directly from your terminal.

Installation

$ npm install -g osmtogeojson

Basic Usage

$ osmtogeojson file.osm > file.geojson

Handling Large Files

For files larger than 100 MB, you may encounter 'process out of memory' errors. It is recommended to increase the memory limit using Node's --max_old_space_size flag. A good rule of thumb is to allocate 4-5 times the input data size in MB.

On Unix systems, you can run the command like this:

$ node --max_old_space_size=8192 `which osmtogeojson` large.osm > large.geojson

#!/bin/bash
$ npm install -g osmtogeojson
$ osmtogeojson file.osm > file.geojson