{"id":24077913,"url":"https://github.com/pypsa-meets-earth/earth-osm","last_synced_at":"2025-04-07T12:03:53.248Z","repository":{"id":62000142,"uuid":"537897934","full_name":"pypsa-meets-earth/earth-osm","owner":"pypsa-meets-earth","description":"Export infrastructure data from OpenStreetMap using Python","archived":false,"fork":false,"pushed_at":"2024-12-22T19:15:20.000Z","size":1040,"stargazers_count":33,"open_issues_count":6,"forks_count":15,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-05T17:36:04.045Z","etag":null,"topics":["earth-osm","open-data","openstreetmap","power","pypsa"],"latest_commit_sha":null,"homepage":"https://pypsa-meets-earth.github.io/earth-osm/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pypsa-meets-earth.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-17T18:32:04.000Z","updated_at":"2025-03-30T14:52:58.000Z","dependencies_parsed_at":"2023-02-15T18:00:58.323Z","dependency_job_id":"1fcbc193-ac71-4ab7-9041-34cac54dc898","html_url":"https://github.com/pypsa-meets-earth/earth-osm","commit_stats":{"total_commits":214,"total_committers":4,"mean_commits":53.5,"dds":0.2990654205607477,"last_synced_commit":"714ab0d9762d3715fdd1ebb1eba6af1773070004"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pypsa-meets-earth%2Fearth-osm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pypsa-meets-earth%2Fearth-osm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pypsa-meets-earth%2Fearth-osm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pypsa-meets-earth%2Fearth-osm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pypsa-meets-earth","download_url":"https://codeload.github.com/pypsa-meets-earth/earth-osm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247526739,"owners_count":20953143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["earth-osm","open-data","openstreetmap","power","pypsa"],"created_at":"2025-01-09T21:00:43.606Z","updated_at":"2025-04-07T12:03:53.225Z","avatar_url":"https://github.com/pypsa-meets-earth.png","language":"Python","funding_links":[],"categories":["Grid Extraction, Transformation and Integration Tools","Energy Systems"],"sub_categories":["Editors and Mapping Tools","Grid Analysis and Planning"],"readme":"\u003cdiv align=\"center\" markdown=1\u003e\n\n# earth-osm\nOne-command to extract infrastructure data from OpenStreetMap\n\n[![][badge-pypi-monthly-downloads]][pypi-url]\n[![][badge-codecov]][codecov-url]\n[![][badge-ci]][gh-repo-url]\n[![][badge-docs]][docs-url]\n[![][badge-pypi]][pypi-url]\n[![][badge-conda]][conda-url]\n[![][badge-release]][gh-release-url]\n[![][badge-license]][license]\n[![][badge-discord]][discord-url]\n\n[![][badge-gh-stars]][gh-stars-url]\n[![][badge-gh-forks]][gh-forks-url]\n[![][badge-gh-issues]][gh-issues-url]\n[![][badge-gh-pulls]][gh-pulls-url]\n\n\u003c/div\u003e\n\n## 📚 Overview\n\nearth-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.\n\n## 🌟 Key Features\n\n- 🔌 Extracts infrastructure data from OSM\n- 🧹 Cleans and standardizes the data *(coming soon)*\n- 🚀 No API rate limits (data served from GeoFabrik)\n- 🐍 Provides a Python API\n- 🖥️ Supports multiprocessing for faster extraction\n- 📊 Outputs data in .csv and .geojson formats\n- 🌍 Supports global data extraction\n- 🖱️ Easy-to-use CLI interface\n\n## 🚀 Getting Started\n\n### Installation\n\nInstall earth-osm using pip (recommended):\n\n```bash\npip install earth-osm\n```\n\nOr with conda:\n\n```bash\nconda install --channel=conda-forge earth-osm\n```\n\n### Basic Usage\n\nExtract OSM data using the CLI:\n\n```bash\nearth_osm extract power --regions benin monaco --features substation line\n```\n\nThis 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`.\n\nLoad the extracted data using pandas:\n\n```python\nimport pandas as pd\nimport geopandas as gpd\n\n# For Pandas\ndf_substations = pd.read_csv('./earth_data/out/BJ_raw_substations.csv')\n\n# For GeoPandas\ngdf_substations = gpd.read_file('./earth_data/out/BJ_raw_substations.geojson')\n```\n\n## 🛠️ CLI Reference\n\n### Extract Command\n\n```bash\nearth_osm extract \u003cprimary\u003e --regions \u003cregion1\u003e \u003cregion2\u003e ... [options]\n```\n\n#### Arguments:\n\n- `\u003cprimary\u003e`: Primary feature to extract (e.g power)\n\n#### Required Options:\n\n- `--regions`: Specify one or more regions using ISO 3166-1 alpha-2, ISO 3166-2 codes, or full names\n\n\u003e **Tip:** A list of regions is available at [regions.md](docs/generated-docs/regions_table.md)\n\n\n#### Optional Arguments:\n\n| Argument | Description | Default |\n|----------|-------------|---------|\n| `--features` | Specify sub-features of the primary feature | All features |\n| `--update` | Update existing data | False |\n| `--no_mp` | Disable multiprocessing | False (MP enabled) |\n| `--data_dir` | Path to data directory | './earth_data' |\n| `--out_dir` | Path to output directory | Same as data_dir |\n| `--out_format` | Export format(s): csv and/or geojson | ['csv', 'geojson'] |\n| `--agg_feature` | Aggregate outputs by feature | False |\n| `--agg_region` | Aggregate outputs by region | False |\n\n## 🐍 Python API\n\nFor more advanced usage, you can use the Python API:\n\n```python\nimport earth_osm as eo\n\neo.save_osm_data(\n    primary_name='power',\n    region_list=['benin', 'monaco'],\n    feature_list=['substation', 'line'],\n    update=False,\n    mp=True,\n    data_dir='./earth_data',\n    out_format=['csv', 'geojson'],\n    out_aggregate=False,\n)\n```\n\n## 🛠️ Development\n\nTo contribute to earth-osm, follow these steps:\n\n1. (Optional) Install a specific version of earth_osm:\n   ```bash\n   pip install git+https://github.com/pypsa-meets-earth/earth-osm.git@\u003crequired-commit-hash\u003e\n   ```\n\n2. (Optional) Create a virtual environment for Python \u003e=3.10:\n   ```bash\n   python3 -m venv .venv\n   source .venv/bin/activate\n   ```\n\n3. Install the development dependencies:\n   ```bash\n   pip install git+https://github.com/pypsa-meets-earth/earth-osm.git\n   pip install -e .[dev]\n   ```\n\n4. Read the [CONTRIBUTING.md](CONTRIBUTING.md) file for more detailed information on how to contribute to the project.\n\n## 📄 License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## 🤝 Community\n\nJoin our [Discord community](https://discord.gg/AnuJBk23FU) to connect with other users and contributors, ask questions, and get support.\n\n## 📚 Documentation\n\nFor more detailed information, check out our [full documentation](https://pypsa-meets-earth.github.io/earth-osm/).\n\n---\n\n\u003cp align=\"center\"\u003e\nMade with ❤️ by the PyPSA meets Earth team\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e \n\u003ca href=\"https://pypsa-meets-earth.github.io/earth-osm/\"\u003e\n    \u003cimg src=\"https://github.com/pypsa-meets-earth/pypsa-meets-earth.github.io/raw/main/assets/img/logo.png\" height=\"50\" alt=\"earth-osm logo\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n\n\u003c!-- LINK GROUP --\u003e\n\n[contributing]: CONTRIBUTING.md\n[license]: LICENSE\n[docs-url]: https://pypsa-meets-earth.github.io/earth-osm/\n[discord-url]: https://discord.gg/AnuJBk23FU\n[pypi-url]: https://pypi.org/project/earth-osm/\n[conda-url]: https://anaconda.org/conda-forge/earth-osm\n[codecov-url]: https://codecov.io/gh/pypsa-meets-earth/earth-osm\n[gh-repo-url]: https://github.com/pypsa-meets-earth/earth-osm\n[gh-release-url]: https://github.com/pypsa-meets-earth/earth-osm/releases\n[gh-stars-url]: https://github.com/pypsa-meets-earth/earth-osm/stargazers\n[gh-forks-url]: https://github.com/pypsa-meets-earth/earth-osm/network/members\n[gh-issues-url]: https://github.com/pypsa-meets-earth/earth-osm/issues\n[gh-pulls-url]: https://github.com/pypsa-meets-earth/earth-osm/pulls\n\n\u003c!-- Primary badges --\u003e\n[badge-pypi-monthly-downloads]: https://img.shields.io/pypi/dm/earth-osm?style=flat\u0026labelColor=black\u0026logoColor=white\u0026logo=pypi\n[badge-codecov]: https://img.shields.io/codecov/c/github/pypsa-meets-earth/earth-osm?style=flat\u0026labelColor=black\u0026logoColor=white\u0026logo=codecov\n[badge-ci]: https://img.shields.io/github/actions/workflow/status/pypsa-meets-earth/earth-osm/main.yml?style=flat\u0026labelColor=black\u0026logoColor=white\u0026logo=github\n[badge-docs]: https://img.shields.io/github/actions/workflow/status/pypsa-meets-earth/earth-osm/docs-ci.yml?style=flat\u0026labelColor=black\u0026logoColor=white\u0026logo=github\n\n[badge-pypi]: https://img.shields.io/pypi/v/earth-osm.svg?style=flat\u0026labelColor=black\u0026logoColor=white\u0026logo=pypi\n[badge-conda]: https://img.shields.io/conda/vn/conda-forge/earth-osm.svg?style=flat\u0026labelColor=black\u0026logoColor=white\u0026logo=conda-forge\n\n[badge-discord]: https://img.shields.io/discord/911692131440148490?style=flat\u0026labelColor=black\u0026logoColor=white\u0026logo=discord\u0026color=blue\n[badge-license]: https://img.shields.io/badge/License-MIT-blue.svg?style=flat\u0026labelColor=black\n[badge-release]: https://img.shields.io/github/v/release/pypsa-meets-earth/earth-osm?style=flat\u0026labelColor=black\u0026logoColor=white\u0026logo=github\n\n\n\n\u003c!-- Secondary badges --\u003e\n[badge-gh-stars]: https://img.shields.io/github/stars/pypsa-meets-earth/earth-osm?style=for-the-badge\u0026labelColor=black\u0026logoColor=white\u0026color=yellow\n[badge-gh-forks]: https://img.shields.io/github/forks/pypsa-meets-earth/earth-osm?style=for-the-badge\u0026labelColor=black\u0026logoColor=white\u0026color=grey\n[badge-gh-issues]: https://img.shields.io/github/issues/pypsa-meets-earth/earth-osm?style=for-the-badge\u0026labelColor=black\u0026logoColor=white\u0026color=red\n[badge-gh-pulls]: https://img.shields.io/github/issues-pr/pypsa-meets-earth/earth-osm?style=for-the-badge\u0026labelColor=black\u0026logoColor=white\u0026color=green","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpypsa-meets-earth%2Fearth-osm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpypsa-meets-earth%2Fearth-osm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpypsa-meets-earth%2Fearth-osm/lists"}