Metadata-Version: 2.4
Name: harvestly
Version: 0.1.0
Summary: US farmers-market statistics: official Python client for the Harvestly Markets open dataset (CC BY 4.0, USDA-derived)
Project-URL: Homepage, https://harvestlymarkets.com
Project-URL: Documentation, https://harvestlymarkets.com/data-sources/
Project-URL: Dataset & methodology, https://harvestlymarkets.com/about/methodology/
Project-URL: State statistics, https://harvestlymarkets.com/farmers-market-statistics/
Author-email: Quinn Vandt <quinn@harvestlymarkets.com>
License-Expression: MIT
License-File: LICENSE
Keywords: csa,dataset,farm-stands,farmers-markets,food,local-food,open-data,statistics,usda
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# harvestly

Official Python client for the [Harvestly Markets](https://harvestlymarkets.com) open dataset:
state-by-state statistics on **8,800+ US farmers markets**, ~2,000 CSA programs, and ~7,800 farm
stands — cleaned, deduplicated, and enriched from the [USDA AMS Local Food
Portal](https://www.usdalocalfoodportal.com/).

- **Data license:** [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) (this client: MIT)
- **Zero dependencies** — Python ≥ 3.9 standard library only
- Data + methodology: [harvestlymarkets.com/data-sources](https://harvestlymarkets.com/data-sources/)
- Human-readable reports: [farmers-market statistics by state](https://harvestlymarkets.com/farmers-market-statistics/)

## Install

```bash
pip install harvestly
```

## Python API

```python
import harvestly

ds = harvestly.load()          # fetches once, then ~24h local cache

ds.national["farmers_markets"] # 8863
ds.state("vt")                 # {'state_name': 'Vermont', 'farmers_markets': ..., ...}
ds.state("California")         # abbreviation or full name

ds.top("website_pct", 5)                       # best online presence
ds.top("farmers_markets", 5, ascending=True)   # fewest markets

harvestly.state_url("ny")   # browse live listings for a state
harvestly.zip_url("12180")  # market finder for a ZIP
```

Each state row: `farmers_markets`, `csa_programs`, `farm_stands`, `snap_ebt_markets`,
`snap_ebt_pct`, `organic_vendor_markets`, `organic_pct`, `markets_with_website`, `website_pct`.

## CLI

```bash
harvestly national
harvestly state ca
harvestly top snap_ebt_pct -n 10
harvestly state vt --json     # machine-readable
```

## Data notes

The dataset is rebuilt from the USDA substrate with documented cleaning: deduplication
(the raw feed double-counts ~270 records), website/season/SNAP enrichment from live state
sources, and per-state aggregation. Full methodology:
[harvestlymarkets.com/about/methodology](https://harvestlymarkets.com/about/methodology/).
Archived copies: [Zenodo (DOI 10.5281/zenodo.21247900)](https://doi.org/10.5281/zenodo.21247900),
Hugging Face, Kaggle, GitHub.

**Attribution (CC BY 4.0):** Harvestly Markets (2026). *US Farmers Market Statistics.*
https://harvestlymarkets.com/farmers-market-statistics/

Found a data issue? Every listing has a correction flow at
[harvestlymarkets.com/submit](https://harvestlymarkets.com/submit/).
