earth-osm

earth-osm is a python package that provides an end-to-end solution to extract & standardize power infrastructure data from OpenStreetmap (OSM).

Features

Extracts power 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
Outputs .csv and .geojson files
Aggregate data per feature or per region
Easy to use CLI interface

Getting Started

Install earth-osm with pip:

pip install earth-osm

Or with conda:

conda install --channel=conda-forge earth-osm

Extract osm data

# Example CLI command
earth_osm extract power --regions benin monaco  --features substation line

This will extract primary feature = power for the regions = benin and monaco and the secondary features = substation and line. By default the resulting .csv and .geojson are stored in ./earth_data/out

Load the substation data for benin using pandas

# 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')

Other Arguments

usage: earth_osm extract primary --regions region1, region2 --features feature1, feature2 --data_dir DATA_DIR [--update] [--mp]

primary (e.g power, water, road, etc) NOTE: currently only power is supported

--regions region1 region2 ... (use either iso3166-1:alpha2 or iso3166-2 codes or full names as given by running 'earth_osm view regions')

--features feature1 feature2 ... (optional, use sub-features of primary feature, e.g. substation, line, etc)

--update (optional, update existing data, default False)

--mp (optional, use multiprocessing, default True)

--data_dir (optional, path to data directory, default './earth_data')

--out_format (optional, export format options csv or geojson, default csv)

--out_aggregate (options, combine outputs per feature, default False)

Advanced Usage

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

(Optional) Intstall 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

Read the CONTRIBUTING.md file.

pip install git+https://github.com/pypsa-meets-earth/earth-osm.git
pip install -r requirements-test.txt

gaybro8777 / earth-osm