osm2geojson

0.3.2 verified Fri May 01 auth: no python

A Python library to convert OSM and Overpass JSON responses into valid GeoJSON. Version 0.3.2 is the latest stable release. The library is actively maintained, with recent bug fixes for polygon hole handling and blacklist/whitelist rules. Releases are sporadic.

pip install osm2geojson

Common errors

error AttributeError: module 'osm2geojson' has no attribute 'overpass2geojson' ↓

cause The function 'overpass2geojson' was renamed to 'json2geojson' in version 0.3.0.

fix

Use osm2geojson.json2geojson(data) instead of osm2geojson.overpass2geojson(data).

error KeyError: 'elements' ↓

cause The input JSON dict does not contain the expected 'elements' key. The library expects the standard Overpass JSON format.

fix

Check your JSON structure; ensure it has an 'elements' list. If from Overpass, use the raw response (the JSON output from the API).

error TypeError: the JSON object must be str, bytes or bytearray, not dict ↓

cause The user passed a Python dict without calling json2geojson, but tried to use json.loads on an already-parsed dict.

fix

Pass the dict directly to osm2geojson.json2geojson(dict). If you have a string, do: geojson = osm2geojson.json2geojson(json.loads(json_string)).

Warnings

gotcha Input must be a parsed JSON dict, not a raw string. If you pass a string, the function will fail. ↓

fix Ensure you pass a dict via json.loads() if reading from a string.

gotcha The 'elements' key in Overpass JSON is required. If your JSON is malformed (e.g., missing 'elements'), the conversion will return an empty FeatureCollection. ↓

fix Validate your Overpass JSON structure before passing to osm2geojson.

deprecated The function 'overpass2geojson' in older versions is deprecated in favor of 'json2geojson'. Using the old name may raise a deprecation warning or be removed. ↓

fix Use json2geojson instead of overpass2geojson.

gotcha Polygon orientation (clockwise/counter-clockwise) is not automatically corrected. The library follows the OSM convention, which may produce invalid GeoJSON if the winding order is wrong. ↓

fix Post-process with a polygon winding fixer if required by your GeoJSON consumer.

Imports

osm2geojson
```
import osm2geojson
```

Quickstart

Converts an OSM JSON dict (e.g., from Overpass API) into a GeoJSON FeatureCollection.

import osm2geojson

# Example: convert an Overpass JSON response to GeoJSON
overpass_json = {
    "elements": [
        {
            "type": "node",
            "id": 1,
            "lat": 50.0,
            "lon": 10.0,
            "tags": {"amenity": "cafe"}
        }
    ]
}

geojson = osm2geojson.json2geojson(overpass_json)
print(geojson)