{"id":51161269,"url":"https://github.com/yharby/OvertureMapsDownloader","last_synced_at":"2026-07-14T22:00:40.879Z","repository":{"id":193778957,"uuid":"689456439","full_name":"yharby/OvertureMapsDownloader","owner":"yharby","description":"Overture Maps Downloader simplifies geospatial data manipulation by integrating the powerful DuckDB, Dask DataFrames, and GDAL/OGR open source tools.","archived":false,"fork":false,"pushed_at":"2024-06-17T23:25:59.000Z","size":16485,"stargazers_count":103,"open_issues_count":12,"forks_count":11,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-01-24T03:40:00.285Z","etag":null,"topics":["duckdb","duckdb-wasm","gdal","geoparque","geospatial","overture-maps","parquet"],"latest_commit_sha":null,"homepage":"https://youssef-harby.github.io/OvertureMapsDownloader/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yharby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-09-09T21:36:30.000Z","updated_at":"2025-11-24T19:39:43.000Z","dependencies_parsed_at":"2023-12-28T06:02:38.214Z","dependency_job_id":"b97b3b28-0286-4723-a0d4-6ac9e8a9546f","html_url":"https://github.com/yharby/OvertureMapsDownloader","commit_stats":{"total_commits":64,"total_committers":2,"mean_commits":32.0,"dds":0.015625,"last_synced_commit":"67dc2cf655ead7706d243bcf8f376405e94a2e5b"},"previous_names":["youssef-harby/overturemapsdownloader","yharby/overturemapsdownloader"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/yharby/OvertureMapsDownloader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yharby%2FOvertureMapsDownloader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yharby%2FOvertureMapsDownloader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yharby%2FOvertureMapsDownloader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yharby%2FOvertureMapsDownloader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yharby","download_url":"https://codeload.github.com/yharby/OvertureMapsDownloader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yharby%2FOvertureMapsDownloader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35480624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-14T02:00:06.603Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["duckdb","duckdb-wasm","gdal","geoparque","geospatial","overture-maps","parquet"],"created_at":"2026-06-26T14:00:25.422Z","updated_at":"2026-07-14T22:00:40.874Z","avatar_url":"https://github.com/yharby.png","language":"Python","funding_links":[],"categories":["Tools and Libraries"],"sub_categories":["Community"],"readme":"# Overture Maps Downloader\n\nThis repository is still under heavy development. Features may change, and documentation will be updated accordingly. Use at your own risk and feel free to contribute!\n\n[![Docker build and push](https://github.com/Youssef-Harby/OvertureMapsDownloader/actions/workflows/docker-build-push.yml/badge.svg)](https://github.com/Youssef-Harby/OvertureMapsDownloader/actions/workflows/docker-build-push.yml)\n[![Deploy static content to Pages](https://github.com/Youssef-Harby/OvertureMapsDownloader/actions/workflows/deploy-react-app.yml/badge.svg)](https://github.com/Youssef-Harby/OvertureMapsDownloader/actions/workflows/deploy-react-app.yml) [![Publish Python Package](https://github.com/Youssef-Harby/OvertureMapsDownloader/actions/workflows/poetry-pypi.yml/badge.svg)](https://github.com/Youssef-Harby/OvertureMapsDownloader/actions/workflows/poetry-pypi.yml)\n\n## Overview\n\nOvertureMapsDownloader is a monorepo that contains two main projects aimed at simplifying the process of working with Overture Maps data in Parquet format.\n\n### DuckDB-WASM with Map\n\nThe first project is a browser-based application that leverages DuckDB-WASM and mapping functionalities. This allows you to query Overture Maps data in Parquet format directly within your web browser. It offers a seamless and interactive way to work with geospatial data without the need for any backend services. The codebase for this project is located in the `/app` folder.\n\n### Data Manipulation/Downloading and Conversion\n\nThe second project focuses on data manipulation, downloading, and conversion of Overture Maps data. It utilizes technologies like DuckDB, Python, and IPython Notebooks, along with GDAL/OGR for data conversion. This project is containerized using Docker, making it easy to integrate into existing pipelines and ETL workflows. For hands-on examples, check out the Jupyter notebooks available in the `examples` folder.\n\nWhether you're a data scientist, a geospatial analyst, or a developer, OvertureMapsDownloader offers comprehensive solutions for your geospatial data needs.\n\n## Table of Contents\n\n- [Overture Maps Downloader](#overture-maps-downloader)\n  - [Overview](#overview)\n    - [DuckDB-WASM with Map](#duckdb-wasm-with-map)\n    - [Data Manipulation/Downloading and Conversion](#data-manipulationdownloading-and-conversion)\n  - [Table of Contents](#table-of-contents)\n    - [DuckDB-WASM in Browser (Developers)](#duckdb-wasm-in-browser-developers)\n    - [Getting Started](#getting-started)\n    - [Visual Demo](#visual-demo)\n    - [Data Manipulation/Downloading and Conversion](#data-manipulationdownloading-and-conversion-1)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n    - [the docker image manily contains the following tools:](#the-docker-image-manily-contains-the-following-tools)\n  - [Usage](#usage)\n    - [Download Geospatial Data](#download-geospatial-data)\n      - [Commands](#commands)\n  - [Examples of downloading data CLI:](#examples-of-downloading-data-cli)\n    - [With Docker:](#with-docker)\n    - [Without Docker you can use the following commands with (`pip install overturemapsdownloader`):](#without-docker-you-can-use-the-following-commands-with-pip-install-overturemapsdownloader)\n    - [Convert Parquet to GeoPackage](#convert-parquet-to-geopackage)\n    - [Convert Parquet to MBTiles (will support tippecanoe in the future)](#convert-parquet-to-mbtiles-will-support-tippecanoe-in-the-future)\n    - [Convert Parquet to ESRI File Geodatabase vector (OpenFileGDB)](#convert-parquet-to-esri-file-geodatabase-vector-openfilegdb)\n  - [Using Jupyter Notebooks (Data Scientists/GIS Analysts)](#using-jupyter-notebooks-data-scientistsgis-analysts)\n  - [Configuration](#configuration)\n  - [Roadmap](#roadmap)\n    - [DuckDB-WASM in Browser (Developers) (ReactJS)](#duckdb-wasm-in-browser-developers-reactjs)\n    - [Data Manipulation/Downloading and Conversion (Python)](#data-manipulationdownloading-and-conversion-python)\n  - [Contributing](#contributing)\n\n### DuckDB-WASM in Browser (Developers)\n\nFor developers interested in running DuckDB-WASM in the browser, the relevant codebase is located in the `/app` folder at the root of the repository. This setup allows you to develop, run, and build the DuckDB-WASM component seamlessly.\n\n### Getting Started\n\n1. Navigate to the `/app` folder:\n\n   ```bash\n   cd /app\n   ```\n\n2. Install the required packages:\n\n   ```bash\n   yarn install\n   ```\n\n   \u003e Note: Make sure you have npm version 18 or above for compatibility.\n\n3. Start the development server:\n\n   ```bash\n   yarn dev\n   ```\n\nthen open http://localhost:5173/OvertureMapsDownloader in your browser\n\n### Visual Demo\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"omd.gif\" alt=\"DuckDB-WASM in action\"\u003e\n\u003c/p\u003e\n\n### Data Manipulation/Downloading and Conversion\n\n## Prerequisites\n\n- Docker and Docker Compose\n- GeoJSON file containing the bounding box polygon (e.g., `bbox.geojson`)\n  **you can make yours easly on https://geojson.io or use `examples/bbox.json` for testing**\n\n## Installation\n\nTo get started, you'll need to pull the Docker image from the GitHub Container Registry:\n\n```bash\ndocker pull ghcr.io/youssef-harby/overturemapsdownloader:latest\n```\n\n#### the docker image manily contains the following tools:\n\n- GDAL/OGR v3.8.4\n- Python v3.10 (and GDAL/OGR Python bindings + duckdb python bindings)\n- DuckDB v0.10.0\n- Jupyter.. and more\n\n## Usage\n\n### Download Geospatial Data\n\n1. Create a folder and place your bounding box polygon in GeoJSON format inside it (e.g., `bbox.geojson`).\n2. Navigate to the folder:\n\n   ```bash\n   cd /examples # e.g., cd /path/to/your/folder contains bbox.geojson and will contain the output file\n   ```\n\n3. Run the following command to download geospatial data:\n\n   ```bash\n   docker run -v $(pwd):/examples ghcr.io/youssef-harby/overturemapsdownloader:latest OMDownloader omaps --theme places --ptype place --bbox /examples/bbox.geojson --output /examples/places.parquet\n   ```\n\n#### Commands\n\nThe omaps Command\n\n```bash\nOMDownloader omaps [OPTIONS]\n```\n\noptions:\n\n- `--theme [admins|buildings|buildings|places|transportation]` Theme of the data to download\n- `--ptype [locality|administrativeBoundary|building|place|water|connector|segment]` Type of the data to download\n- `--bbox PATH` Bounding box polygon in GeoJSON format as a path to a file\n- `--output PATH` Output file path (e.g., `places.parquet`)\n- `--help` Show this message and exit.\n\n## Examples of downloading data CLI:\n\n### With Docker:\n\n```bash\n# admins/locality\ndocker run -v $(pwd):/examples ghcr.io/youssef-harby/overturemapsdownloader:latest OMDownloader omaps --theme admins --ptype locality --bbox /examples/bbox.geojson --output /examples/locality.parquet\n\n# admins/administrativeBoundary\ndocker run -v $(pwd):/examples ghcr.io/youssef-harby/overturemapsdownloader:latest OMDownloader omaps --theme admins --ptype administrativeBoundary --bbox /examples/bbox.geojson --output /examples/admins.parquet\n\n# buildings/building\ndocker run -v $(pwd):/examples ghcr.io/youssef-harby/overturemapsdownloader:latest OMDownloader omaps --theme buildings --ptype building --bbox /examples/bbox.geojson --output /examples/building.parquet\n\n# places/place\ndocker run -v $(pwd):/examples ghcr.io/youssef-harby/overturemapsdownloader:latest OMDownloader omaps --theme places --ptype place --bbox /examples/bbox.geojson --output /examples/place.parquet\n\n# transportation/connector\ndocker run -v $(pwd):/examples ghcr.io/youssef-harby/overturemapsdownloader:latest OMDownloader omaps --theme transportation --ptype connector --bbox /examples/bbox.geojson --output /examples/connector.parquet\n\n# transportation/segment\ndocker run -v $(pwd):/examples ghcr.io/youssef-harby/overturemapsdownloader:latest OMDownloader omaps --theme transportation --ptype segment --bbox /examples/bbox.geojson --output /examples/segment.parquet\n```\n\n### Without Docker you can use the following commands with (`pip install overturemapsdownloader`):\n\n```bash\n# admins/locality\nOMDownloader omaps --theme admins --ptype locality --bbox examples/bbox.geojson --output examples/locality.parquet\n\n# admins/administrativeBoundary\nOMDownloader omaps --theme admins --ptype administrativeBoundary --bbox examples/bbox.geojson --output examples/admins.parquet\n\n# buildings/building\nOMDownloader omaps --theme buildings --ptype building --bbox examples/bbox.geojson --output examples/building.parquet\n\n# places/place\nOMDownloader omaps --theme places --ptype place --bbox examples/bbox.geojson --output examples/place.parquet\n\n# transportation/connector\nOMDownloader omaps --theme transportation --ptype connector --bbox examples/bbox.geojson --output examples/connector.parquet\n\n# transportation/segment\nOMDownloader omaps --theme transportation --ptype segment --bbox examples/bbox.geojson --output examples/segment.parquet\n```\n\n### Convert Parquet to GeoPackage\n\nTo convert the downloaded data to GeoPackage format, run the following command:\n\n```bash\ndocker run -v $(pwd):/examples ghcr.io/youssef-harby/overturemapsdownloader:latest ogr2ogr /examples/output.gpkg /examples/places.parquet\n```\n\n### Convert Parquet to MBTiles (will support tippecanoe in the future)\n\n```bash\ndocker run -v $(pwd):/examples ghcr.io/youssef-harby/overturemapsdownloader:latest ogr2ogr -dsco MAXZOOM=14 /examples/output.mbtiles /examples/places.parquet\n```\n\n### Convert Parquet to ESRI File Geodatabase vector (OpenFileGDB)\n\n```bash\ndocker run -v $(pwd):/examples ghcr.io/youssef-harby/overturemapsdownloader:latest ogr2ogr /examples/output.gdb /examples/places.parquet\n```\n\n## Using Jupyter Notebooks (Data Scientists/GIS Analysts)\n\nIf you prefer to use Jupyter notebooks for your geospatial data manipulation tasks, you can easily set up a Jupyter environment using Docker Compose.\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/Youssef-Harby/OvertureMapsDownloader.git\n   ```\n\n2. Navigate to the repository folder:\n\n   ```bash\n   cd OvertureMapsDownloader\n   ```\n\n3. Run the following Docker Compose command:\n\n   ```bash\n   docker compose up\n   ```\n\nThis will start a Jupyter notebook server accessible at http://localhost:8888/lab.\n\n## Configuration\n\nFor advanced configurations, please refer to the `config.yml` file.\n\n## Roadmap\n\n### DuckDB-WASM in Browser (Developers) (ReactJS)\n\n- [ ] Add Popup on click of the feautre to show the result of the query\n- [ ] Add a button to use local parquet url instead of the remote one\n- [ ] Add a button to download the result of the query as GeoJSON..etc\n- [ ] Add a loading spinner while the query is running\n- [x] Query by bbox drawn on the map\n- [ ] feel free to add more ...\n\n### Data Manipulation/Downloading and Conversion (Python)\n\n- [ ] Resolve JSON values to be parsed to the correct data type [OSGeo/gdal#8227](https://github.com/OSGeo/gdal/issues/8227)\n\n## Contributing\n\nEveryone is invited to contribute to this project. Whether you're a beginner or experienced, your help is valuable. Don't worry about not getting it right the first time; the idea is to grow and learn together.\n\nYou can contribute by:\n\n- Commenting on or adding to [existing issues](https://github.com/Youssef-Harby/OvertureMapsDownloader/issues)\n- Starting or participating in [discussions](https://github.com/Youssef-Harby/OvertureMapsDownloader/discussions)\n\nIf you're new and have questions or need guidance, the [discussions](https://github.com/Youssef-Harby/OvertureMapsDownloader/discussions) page is a great place to start.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyharby%2FOvertureMapsDownloader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyharby%2FOvertureMapsDownloader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyharby%2FOvertureMapsDownloader/lists"}