๐ 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
Tip: A list of regions is available at regions.md
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