Metadata-Version: 2.4
Name: birdlife-hotspot-finder
Version: 0.1.0
Summary: Find data gaps in eBird coverage for volunteer survey prioritization
Project-URL: Homepage, https://github.com/birdlife-tools/volunteer-hotspot-finder
Project-URL: Documentation, https://github.com/birdlife-tools/volunteer-hotspot-finder#readme
Project-URL: Repository, https://github.com/birdlife-tools/volunteer-hotspot-finder
Project-URL: Issues, https://github.com/birdlife-tools/volunteer-hotspot-finder/issues
Author: BirdLife Tools Community
License-Expression: MIT
License-File: LICENSE
Keywords: birdwatching,citizen-science,conservation,data-gaps,ebird
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: fastavro>=1.9; extra == 'dev'
Requires-Dist: jsonschema>=4.22; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Description-Content-Type: text/markdown

# Volunteer Hotspot Finder

Find data gaps in eBird coverage and propose survey missions to volunteers.

## Status

🔨 **In Progress** — Foundation phase

## Problem

Birdwatchers typically visit popular, already well-surveyed locations. This creates massive "blind spots" — areas with low observation coverage despite high biodiversity potential.

## Solution

Grid-based analysis that identifies geographic cells with low eBird coverage, ranks them by priority, and outputs actionable survey recommendations.

## Installation

```bash
pip install birdlife-hotspot-finder
```

## Usage

```python
from birdlife_hotspot_finder import HotspotFinder

finder = HotspotFinder.from_env()  # Reads EBIRD_API_KEY
gaps = await finder.find_gaps(region="RS", limit=10)
```

## Output Formats

- JSON (API response envelope)
- CSV (spreadsheet import)
- GeoJSON (maps — Leaflet, QGIS)

## API Response Convention

Follows [BirdLife API Response Convention](https://github.com/birdlife-tools/birdlife-schema):

```json
{
  "data": [
    {
      "locationID": "...",
      "name": "Grid cell 44.8N 20.4E",
      "decimalLatitude": 44.8,
      "decimalLongitude": 20.4,
      "extensions": {
        "coverage.checklistCount": "0",
        "coverage.gapType": "spatial",
        "coverage.priorityScore": "0.85"
      }
    }
  ],
  "meta": {
    "resultType": "coverage-gaps",
    "gridSizeKm": "10"
  }
}
```

## Community

[![Matrix](https://img.shields.io/badge/Matrix-Chat-black?logo=matrix)](https://matrix.to/#/#volunteer-hotspot-finder:matrix.org)

## License

MIT — see [LICENSE](LICENSE)
