Python tool to extract large-amounts of OpenStreetMap data
Project description
earth-osm
Extract Infrastructure data from OpenStreetMap
📚 Overview
earth-osm downloads, filters, cleans and exports infrastructure data from OpenStreetMap (OSM). It provides a Python API and a CLI interface to extract data for various infrastructure types, such as power lines, substations, and more.
🌟 Key Features
- 🔌 Extracts infrastructure data from OSM
- 🧹 Cleans and standardizes the data (coming soon)
- 🚀 No API rate limits (data served from GeoFabrik)
- 🐍 Provides a Python API
- 🖥️ Supports multiprocessing for faster extraction
- 📊 Outputs data in .csv and .geojson formats
- 🌍 Supports global data extraction
- 🖱️ Easy-to-use CLI interface
🚀 Getting Started
Installation
Install earth-osm using pip (recommended):
pip install earth-osm
Or with conda:
conda install --channel=conda-forge earth-osm
Basic Usage
Extract OSM data using the CLI:
earth_osm extract power --regions benin monaco --features substation line
This command extracts power infrastructure data for Benin and Monaco, focusing on substations and power lines. By default, the resulting .csv and .geojson files are stored in ./earth_data/out
.
Load the extracted data using pandas:
import pandas as pd
import geopandas as gpd
# For Pandas
df_substations = pd.read_csv('./earth_data/out/BJ_raw_substations.csv')
# For GeoPandas
gdf_substations = gpd.read_file('./earth_data/out/BJ_raw_substations.geojson')
🛠️ CLI Reference
Extract Command
earth_osm extract <primary> --regions <region1> <region2> ... [options]
Arguments:
<primary>
: Primary feature to extract (e.g power)
Required Options:
--regions
: Specify one or more regions using ISO 3166-1 alpha-2, ISO 3166-2 codes, or full names
Optional Arguments:
Argument | Description | Default |
---|---|---|
--features |
Specify sub-features of the primary feature | All features |
--update |
Update existing data | False |
--no_mp |
Disable multiprocessing | False (MP enabled) |
--data_dir |
Path to data directory | './earth_data' |
--out_dir |
Path to output directory | Same as data_dir |
--out_format |
Export format(s): csv and/or geojson | ['csv', 'geojson'] |
--agg_feature |
Aggregate outputs by feature | False |
--agg_region |
Aggregate outputs by region | False |
🐍 Python API
For more advanced usage, you can use the Python API:
import earth_osm as eo
eo.save_osm_data(
primary_name='power',
region_list=['benin', 'monaco'],
feature_list=['substation', 'line'],
update=False,
mp=True,
data_dir='./earth_data',
out_format=['csv', 'geojson'],
out_aggregate=False,
)
🛠️ Development
To contribute to earth-osm, follow these steps:
-
(Optional) Install a specific version of earth_osm:
pip install git+https://github.com/pypsa-meets-earth/earth-osm.git@<required-commit-hash>
-
(Optional) Create a virtual environment for Python >=3.10:
python3 -m venv .venv source .venv/bin/activate
-
Install the development dependencies:
pip install git+https://github.com/pypsa-meets-earth/earth-osm.git pip install -r requirements-test.txt
-
Read the CONTRIBUTING.md file for more detailed information on how to contribute to the project.
📄 License
This project is licensed under the MIT License. See the LICENSE file for details.
🤝 Community
Join our Discord community to connect with other users and contributors, ask questions, and get support.
📚 Documentation
For more detailed information, check out our full documentation.
Made with ❤️ by the PyPSA meets Earth team
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file earth_osm-2.2.tar.gz
.
File metadata
- Download URL: earth_osm-2.2.tar.gz
- Upload date:
- Size: 132.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | de61735f5ab8a6f905d3745b8ab26411d6e72b6bd88eceb165f089ec776e3a7b |
|
MD5 | 02c2daa3056c57d85e0823072d5c139b |
|
BLAKE2b-256 | 4691175f059fe07309efb8402a1511ce913de6edc509e8a7b4dc34fb47d9e2fa |
File details
Details for the file earth_osm-2.2-py3-none-any.whl
.
File metadata
- Download URL: earth_osm-2.2-py3-none-any.whl
- Upload date:
- Size: 133.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6922d70b02bbd50f6bcf4e187f9b6b44424128ba52da12f16e01098057de61d3 |
|
MD5 | 1c6d36f9ba82c4583219d0b9ac7325b9 |
|
BLAKE2b-256 | b29cd877f9057b21732d6a72ad2f6b49df43b78c08660b28e89ae81c94358d4b |