Metadata-Version: 2.1
Name: overture_maps_geoparquet_package
Version: 0.1.2
Summary: A Python package for downloading and processing Overture Maps geospatial data with configurable bounding box extraction and data management.
License: GPL-3.0-only
Author: ediakatos
Author-email: ediakatos@mapaction.org
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: aiobotocore (==2.15.1)
Requires-Dist: aiohappyeyeballs (==2.4.3)
Requires-Dist: aiohttp (==3.10.9)
Requires-Dist: aioitertools (==0.12.0)
Requires-Dist: aiosignal (==1.3.1)
Requires-Dist: async-timeout (==4.0.3)
Requires-Dist: attrs (==24.2.0)
Requires-Dist: botocore (==1.35.23)
Requires-Dist: certifi (==2024.8.30)
Requires-Dist: click (==8.1.7)
Requires-Dist: frozenlist (==1.4.1)
Requires-Dist: fsspec (==2024.9.0)
Requires-Dist: geopandas (==1.0.1)
Requires-Dist: idna (==3.10)
Requires-Dist: jmespath (==1.0.1)
Requires-Dist: multidict (==6.1.0)
Requires-Dist: numpy (==2.1.2)
Requires-Dist: overturemaps (==0.9.0)
Requires-Dist: packaging (==24.1)
Requires-Dist: pandas (==2.2.3)
Requires-Dist: propcache (==0.2.0)
Requires-Dist: pyarrow (==17.0.0)
Requires-Dist: pyogrio (==0.10.0)
Requires-Dist: pyproj (==3.7.0)
Requires-Dist: python-dateutil (==2.9.0.post0)
Requires-Dist: pytz (==2024.2)
Requires-Dist: s3fs (==2024.9.0)
Requires-Dist: shapely (==2.0.6)
Requires-Dist: six (==1.16.0)
Requires-Dist: typing-extensions (==4.12.2)
Requires-Dist: tzdata (==2024.2)
Requires-Dist: urllib3 (==2.2.3)
Requires-Dist: wrapt (==1.16.0)
Requires-Dist: yarl (==1.14.0)
Description-Content-Type: text/markdown


# Overture Maps Geoparquet Package

![PyPI](https://img.shields.io/pypi/v/overture_maps_geoparquet_package)
![License](https://img.shields.io/pypi/l/overture_maps_geoparquet_package)
![Python](https://img.shields.io/pypi/pyversions/overture_maps_geoparquet_package)

## Overview

The **Overture Maps Geoparquet Package** is a Python library designed for downloading and processing geospatial data from Overture Maps in a user-friendly way. This package allows users to specify an Area of Interest (AOI) through a GeoJSON file, automatically extract its bounding box, and download relevant geospatial data types, such as buildings, land use, and infrastructure, in GeoParquet format.

## Features

- **Automated Bounding Box Extraction**: Parses a GeoJSON file and extracts the bounding box for easy area targeting.
- **Flexible Data Downloading**: Downloads various data types (e.g., buildings, infrastructure) in GeoParquet format for efficient storage and analysis.
- **Easy Command-Line and Script Integration**: The package provides a simple interface, allowing users to start the download process with a single function call.
- **Data Organization**: Downloads are organized into folders based on the AOI and data type, keeping data management straightforward.

## Installation

To install the package, use `pip`:

```bash
pip install overture_maps_geoparquet_package
```

## Usage

Here’s a quick guide on how to use the package:

1. **Prepare a GeoJSON File**

   Create a GeoJSON file that defines your area of interest (AOI). Save it in your project directory (e.g., `my_area.json`).

2. **Run the Download Function**

   Import and call `download_overture_data`, passing the path to your GeoJSON file:

   ```python
   from overture_maps_geoparquet_package import download_overture_data

   # Download geospatial data for the specified area
   download_overture_data("my_area.json")
   ```

   This will:
   - Extract the bounding box from your GeoJSON file.
   - Download geospatial data (e.g., buildings, land use, infrastructure) for the AOI.
   - Save the data in organized folders within the current directory.

### Example

```python
from overture_maps_geoparquet_package import download_overture_data

# Specify the path to your GeoJSON file
geojson_path = "path/to/your_area.json"

# Start the download process
download_overture_data(geojson_path)
```

This code will automatically download the specified data types in GeoParquet format, organized by type.

### Custom Output Directory

The `download_overture_data` function allows users to specify a custom directory to store downloaded data. By default, the data will be saved in a directory named `overture_data` in the current working directory. However, if you want to store the data in a different location, you can pass the desired path as a second argument.

```python
from overture_maps_geoparquet_package import download_overture_data

# Specify the path to your GeoJSON file
geojson_path = "path/to/your_area.json"

# Start the download process with a custom directory
download_overture_data(geojson_path, "custom/data/directory")
```

In this example:
- **Default behavior**: If no second argument is provided, the data will be saved in `overture_data`.
- **Custom directory**: If you specify a custom directory (e.g., `"custom_data_directory"`), the data will be stored there instead.

This flexibility allows you to organize downloaded data more effectively, especially if you work with multiple Areas of Interest (AOIs) or projects.

## Data Types Supported

The following data types are downloaded for each AOI:
- **address**
- **building**
- **division**
- **infrastructure**
- **land use**
- **water**
- And more...

Each type is saved in a folder structure organized by data category.

## Project Structure

The project follows a standard layout:
```
overture_maps_geoparquet_package/
├── json/                 # Stores GeoJSON files
├── overture_data/        # Downloaded data, organized by AOI and type
├── src/                  # Source code for the package
├── tests/                # Unit tests
├── README.md             # Project documentation
├── pyproject.toml        # Project configuration
└── requirements.txt      # Dependency management
```

## Contributing

Contributions are welcome! Feel free to open issues or submit pull requests for feature requests, bug fixes, or improvements.

1. Fork the repository
2. Create a new branch (`git checkout -b feature-branch`)
3. Make your changes
4. Submit a pull request

## License

This project is licensed under the GPL-3.0 License. See the `LICENSE` file for more details.

## Contact

For questions, please contact **ediakatos@mapaction.org**.

