earth-osm

Provides a Python API and a CLI interface to extract data for various power infrastructure types, such as power lines, substations, and more.
https://github.com/pypsa-meets-earth/earth-osm

Category: Energy Systems
Sub Category: Grid Analysis and Planning

Keywords

earth-osm open-data openstreetmap power pypsa

Keywords from Contributors

energy-system-model energy-system investment-optimization operational-optimization power-system-model power-system-planning pypsa-africa pypsa-earth scenario-analysis energy-system-planning

Last synced: about 23 hours ago
JSON representation

Repository metadata

Export infrastructure data from OpenStreetMap using Python

Host: GitHub
URL: https://github.com/pypsa-meets-earth/earth-osm
Owner: pypsa-meets-earth
License: mit
Created: 2022-09-17T18:32:04.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2024-12-22T19:15:20.000Z (4 months ago)
Last Synced: 2025-04-05T17:36:04.045Z (21 days ago)
Topics: earth-osm, open-data, openstreetmap, power, pypsa
Language: Python
Homepage: https://pypsa-meets-earth.github.io/earth-osm/
Size: 1020 KB
Stars: 33
Watchers: 2
Forks: 15
Open Issues: 6
Releases: 16
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

earth-osm

One-command to 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

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 -e .[dev]

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.

Owner metadata

Name: PyPSA meets Earth
Login: pypsa-meets-earth
Email:
Kind: organization
Description: An open source energy system model initiative for our Earth
Website: https://pypsa-meets-earth.github.io/
Location:
Twitter: pypsameetsearth
Company:
Icon url: https://avatars.githubusercontent.com/u/84225086?v=4
Repositories: 11
Last ynced at: 2023-03-04T04:30:40.464Z
Profile URL: https://github.com/pypsa-meets-earth

GitHub Events

Total

Create event: 9
Commit comment event: 1
Release event: 9
Issues event: 5
Watch event: 5
Delete event: 6
Issue comment event: 22
Push event: 23
Pull request review event: 1
Pull request event: 6
Fork event: 4

Last Year

Create event: 9
Commit comment event: 1
Release event: 9
Issues event: 5
Watch event: 5
Delete event: 6
Issue comment event: 22
Push event: 23
Pull request review event: 1
Pull request event: 6
Fork event: 4

Committers metadata

Last synced: 7 days ago

Total Commits: 260
Total Committers: 4
Avg Commits per committer: 65.0
Development Distribution Score (DDS): 0.204

Commits in past year: 26
Committers in past year: 3
Avg Commits per committer in past year: 8.667
Development Distribution Score (DDS) in past year: 0.5

Name	Email	Commits
mnm-matin	m**9@g**m	207
Max Parzen	m**n@e**k	30
Davide Fioriti	f**s@g**m	22
Fabian Hofmann	f**f@g**e	1

Committer domains:

gmx.de: 1
ed.ac.uk: 1

Issue and Pull Request metadata

Last synced: 2 days ago

Total issues: 41
Total pull requests: 20
Average time to close issues: 3 months
Average time to close pull requests: 5 days
Total issue authors: 14
Total pull request authors: 5
Average comments per issue: 1.93
Average comments per pull request: 1.45
Merged pull request: 18
Bot issues: 0
Bot pull requests: 0

Past year issues: 6
Past year pull requests: 4
Past year average time to close issues: 23 days
Past year average time to close pull requests: 9 days
Past year issue authors: 6
Past year pull request authors: 2
Past year average comments per issue: 2.33
Past year average comments per pull request: 3.0
Past year merged pull request: 4
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/pypsa-meets-earth/earth-osm

Top Issue Authors

pz-max (15)
davide-f (8)
mnm-matin (6)
DeniseGiub (2)
zoobar (1)
dziegler991 (1)
ekatef (1)
bobbyxng (1)
FabianHofmann (1)
simulkade (1)
Wuhochi (1)
jome1 (1)
LRydin (1)
FlorianK13 (1)

Top Pull Request Authors

pz-max (8)
davide-f (7)
mnm-matin (3)
FabianHofmann (1)
simulkade (1)

Top Issue Labels

enhancement (22)
question (21)
bug (16)
help wanted (15)

Top Pull Request Labels

Package metadata

Total packages: 1
Total downloads:
- pypi: 811 last-month
Total dependent packages: 0
Total dependent repositories: 0
Total versions: 16
Total maintainers: 3

pypi.org: earth-osm

Python tool to extract large-amounts of OpenStreetMap data

Homepage: https://github.com/pypsa-meets-earth/earth-osm/
Documentation: https://earth-osm.readthedocs.io/
Licenses: MIT License
Latest release: 0.1.0 (published about 2 years ago)
Last Synced: 2025-04-25T03:01:01.545Z (2 days ago)
Versions: 16
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 811 Last month
Rankings:
- Dependent packages count: 6.633%
- Downloads: 12.349%
- Forks count: 13.564%
- Average: 16.528%
- Stargazers count: 19.483%
- Dependent repos count: 30.611%
Maintainers (3)
- mnm-matin
- pz-max
- davidsf

Dependencies

requirements-test.txt pypi

black * test
codecov * test
coverage * test
flake8 * test
gitchangelog * test
isort * test
mkdocs * test
mypy * test
pytest * test
pytest-cov * test

requirements.txt pypi

geopandas *
pandas *
protobuf *
requests *
tqdm *

.github/workflows/main.yml actions

actions/checkout v2 composite
actions/setup-python v2 composite
codecov/codecov-action v3 composite

.github/workflows/release.yml actions

actions/checkout v2 composite
actions/checkout v1 composite
actions/setup-python v1 composite
softprops/action-gh-release v1 composite

setup.py pypi

geopandas *
pandas *
protobuf >=4.21.1
requests *
tqdm *

Score: 11.751816373252076

earth-osm

Keywords

Keywords from Contributors

Repository metadata

README.md

earth-osm

📚 Overview

🌟 Key Features

🚀 Getting Started

Installation

Basic Usage

🛠️ CLI Reference

Extract Command

Arguments:

Required Options:

Optional Arguments:

🐍 Python API

🛠️ Development

📄 License

🤝 Community

📚 Documentation

Owner metadata

GitHub Events

Total

Last Year

Committers metadata

Committer domains:

Issue and Pull Request metadata

Top Issue Authors

Top Pull Request Authors

Top Issue Labels

Top Pull Request Labels

Package metadata

pypi.org: earth-osm

Dependencies