OSM Data Download

Download OpenStreetMap features via the Overpass API. Query by bounding box, raw tag, semantic preset, or administrative place name (e.g. "北京市朝阳区"). Output GeoJSON and/or Shapefile, optionally zipped, with an automatic QA summary.

Features

• By bbox + tag: Download roads, buildings, POIs, landuse, natural features
• By place name (NEW): download-place --place "北京市朝阳区" --preset water resolves the admin polygon via Nominatim, queries within it, optionally clips to the boundary, and writes a QA summary
• Semantic presets (NEW): water / road / building / green combine multiple tag filters in one Overpass query
• Multi-format export (NEW): --formats geojson,shapefile writes both at once; mixed geometry is auto-split
• Shapefile zip (NEW): --zip-shapefile produces a complete .zip bundle (.shp/.shx/.dbf/.prj/.cpg) ready for QGIS/ArcGIS
• Boundary clipping (NEW): cross-border features are clipped to the admin polygon so the output exactly matches the requested area
• QA summary (NEW): --qa writes a JSON next to the outputs with feature count, geometry stats, bbox, CRS, the resolved place (OSM id, admin level, display name), the Overpass query that ran, and the list of output files
• Custom Overpass QL: Run your own queries
• Multiple outputs: GeoJSON and Shapefile
• Rate limiting & endpoint fallback: tries multiple Overpass mirrors on 429/504
• UTF-8 encoded Shapefile DBF + .cpg: Chinese names survive into QGIS/ArcGIS
• Tag reference: Built-in list of common OSM tags

Common Feature Types

Usage

Download roads in a bounding box

python scripts\osm-data-download.py download \
  --bbox "116.0,39.5,116.8,40.2" \
  --feature highway --output roads.geojson

Download buildings

python scripts\osm-data-download.py download \
  --bbox "116.3,39.8,116.5,40.0" \
  --feature building --output buildings.geojson --format geojson

Custom Overpass QL query

python scripts\osm-data-download.py query \
  --query '[out:json][timeout:60];(node["amenity"="restaurant"](39.8,116.3,40.0,116.5););out body;' \
  --output restaurants.geojson

Download by place name (NEW)

# One-shot: water features in Chaoyang District, Beijing
python scripts\osm-data-download.py download-place \
  --place "北京市朝阳区" \
  --preset water \
  --formats "geojson,shapefile" \
  --zip-shapefile \
  --qa \
  -o chaoyang_water

Outputs (with mixed geometry auto-split into Point/LineString/Polygon shapefiles):

• chaoyang_water.geojson — all features
• chaoyang_water_Point.shp + sidecars
• chaoyang_water_LineString.shp + sidecars
• chaoyang_water_Polygon.shp + sidecars
• chaoyang_water.zip — all shapefile sidecars in one archive
• chaoyang_water.qa.json — feature count, bbox, CRS, OSM place, query, output files

Download by place + raw feature

python scripts\osm-data-download.py download-place \
  --place "成都市" \
  --feature highway \
  -o chengdu_roads.geojson

Disable boundary clipping

By default, features are clipped to the admin polygon. To get the raw bbox-only result:

python scripts\osm-data-download.py download-place --place "朝阳区" --preset water --no-clip -o x

List common tags and presets

python scripts\osm-data-download.py list-tags

Installation

pip install requests>=2.28.0 tqdm>=4.64.0
# Or: pip install -r scripts/requirements.txt

Parameters

download (bbox + tag)

• --bbox: Bounding box as lon_min,lat_min,lon_max,lat_max
• --feature: Feature type (highway, building, amenity, shop, tourism, landuse, natural, waterway)
• --value: Specific tag value (e.g., restaurant, motorway). Omit for all values.
• --output: Output file path
• --format: Output format (geojson, shapefile)
• --query: Custom Overpass QL query string
• --timeout: API timeout in seconds (default: 60)
• --rate-delay: Delay between requests in seconds (default: 1.0)

download-place (NEW: by admin place name)

• --place: Chinese or English place name (e.g. 北京市朝阳区, Chaoyang District, Beijing)
• --preset: Semantic preset (water, road, building, green) — combines multiple tag filters in one Overpass query
• --feature: Alternative to --preset; same choices as download
• --value: Specific tag value (with --feature)
• -o/--output: Base output path (extensions are auto-set per format)
• --formats: Comma-separated list, e.g. geojson,shapefile. Default: single format from --format.
• --zip-shapefile: Also write a complete .zip of the shapefile sidecars
• --no-clip: Skip clipping to the admin polygon (default: clip)
• --qa: Write a QA summary JSON
• --timeout, --rate-delay: same as download

Output

• GeoJSON: Standard GeoJSON with OSM tags as properties
• Shapefile: ESRI Shapefile with attribute table

Geometry Types

OSM features come in three geometry types — choose based on your use case:

The tool automatically detects geometry type. Use --geometry-type to filter.

Maximum Bounding Box Size

Large bounding boxes cause timeouts and excessive data:

# Auto-split large bbox into 4 sub-queries
python scripts\osm-data-download.py download \
  --bbox "115.5,39.0,117.5,41.0" \
  --feature building --output buildings.geojson --split-bbox 4

Shapefile Output

Export directly to ESRI Shapefile format:

python scripts\osm-data-download.py download \
  --bbox "116.3,39.8,116.5,40.0" \
  --feature building --output buildings.shp --format shapefile

Note: Shapefile column names are truncated to 10 characters. Use --format geojson for full attribute names.

Character Encoding

Shapefile attribute tables use UTF-8 encoding by default. If you see garbled text in ArcGIS:

• Set environment variable: SHAPE_ENCODING=UTF-8
• Or open in QGIS (handles UTF-8 natively)
• GeoJSON output is always UTF-8

Error Handling and Retry Logic

The tool handles common HTTP errors automatically:

Use --max-retries 5 and --retry-delay 120 to customize retry behavior.

Alternative Overpass Endpoints

If the primary endpoint is slow or unavailable:

Specify with --endpoint https://overpass.kumi.systems/api/interpreter.

Empty Results Handling

If a query returns no features:

1. Verify bbox coordinates (lon/lat order, sign)
2. Check tag spelling against OSM wiki
3. Try larger bbox — the area may have no mapped features
4. Use list-tags to see available features in the area

The tool prints a warning and exits gracefully on empty results.

Semantic Presets

Presets combine multiple tag filters in a single Overpass query, so the result covers everything matching that semantic concept without you having to know the OSM tag vocabulary:

QA Summary

When --qa is used, a JSON file is written next to the outputs with this shape:

{
  "generated_at": "2026-07-25T12:44:15+00:00",
  "generator": "osm-data-download",
  "feature_count": 979,
  "geometry_types": {"Point": 2, "Polygon": 793, "LineString": 184},
  "property_keys": ["name", "name:zh", "natural", "waterway", "..."],
  "bbox": [116.3447, 39.8089, 116.6392, 40.1101],
  "crs": "EPSG:4326 (WGS84)",
  "place": {
    "query": "北京市朝阳区",
    "display_name": "朝阳区, 北京市, 中国",
    "osm_type": "relation", "osm_id": 2988933,
    "admin_level": "6",
    "bbox": [116.3447, 39.8089, 116.6392, 40.1101],
    "clipped_to_boundary": true
  },
  "preset": {"name": "water", "filters": ["..."]},
  "output_formats": ["geojson", "shapefile"],
  "output_files": ["chaoyang_water.geojson", "chaoyang_water.zip"]
}

Chinese Place Name Resolution

download-place calls Nominatim with countrycodes=cn and runs multiple attempts (the raw place string, a structured {state, city, county} query, and the original string with whitespace) so a name like 朝阳区, 北京市朝阳区, or 朝阳区, 北京市 all resolve to the same relation (OSM relation/2988933 for Chaoyang, Beijing). If the top candidate is ambiguous (multiple admin polygons with the same name), the command raises AmbiguousPlaceError and lists the candidates rather than silently picking one.

Please cite OpenStreetMap data (required by ODbL license):

@misc{osm_contributors,
  author       = {{OpenStreetMap contributors}},
  title        = {OpenStreetMap Data},
  howpublished = {\url{https://www.openstreetmap.org}},
  year         = {2024},
  note         = {ODbL License}
}

@software{osm_data_download,
  author  = {ruiduobao},
  title   = {OSM Data Download Tool},
  url     = {https://github.com/ruiduobao/osm-data-download},
  version = {0.1.0},
  year    = {2024},
}

When using OSM data, display: © OpenStreetMap contributors (ODbL).

Troubleshooting

API Information

• Endpoint: https://overpass-api.de/api/interpreter (with fallback to overpass.kumi.systems and overpass.private.coffee on 429/504)
• No API key required
• Nominatim: https://nominatim.openstreetmap.org/search (with fallback to nominatim.openstreetmap.fr when the main endpoint is rate-limited)
• Rate limits: Please be respectful. Large queries may take time.
• Data license: ODbL (OpenStreetMap contributors)

Dependencies

requests>=2.28.0
tqdm>=4.64.0

Data Source

OpenStreetMap via Overpass API. Data © OpenStreetMap contributors (ODbL).

Visualization

• QGIS: Load output GeoJSON/Shapefile directly → Layer → Add Layer → Add Vector Layer
• Python (geopandas): gdf = gpd.read_file('output.geojson'); gdf.plot()
• Leaflet/Mapbox: Convert to GeoJSON and load in web map
• Kepler.gl: Drag-and-drop GeoJSON for interactive visualization

Advanced Usage

Batch Multi-City Download

# Download buildings for multiple cities
declare -A cities=( ["北京"]="116.0 39.8 116.8 40.2" ["上海"]="121.0 30.8 122.0 31.5" )
for city in "${!cities[@]}"; do
  python scripts\osm-data-download.py download     --feature building --bbox ${cities[$city]}     --output osm_${city}_buildings.geojson
  sleep 2
done

CI/CD Integration (GitHub Actions)

# .github/workflows/update-osm.yml
name: Update OSM Data