harvestly 0.1.0__tar.gz

harvestly-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Build artifacts
+node_modules/
+.astro/
+dist/
+.cache/
+__pycache__/
+.env
+.env.local
+.session-active
+
+# Data — raw + canonical, regenerated by ingest pipeline
+data/raw/
+data/canonical/
+research/_phase0_data/
+
+# Memory: do not commit transient session markers
+.memory/.session-active
+
+# OS
+.DS_Store
+*.log
+
+# Operator-made banner reformats (D-1 image resized to Reddit/YouTube slots — not source)
+launch/assets/D-1_*
+
+# Wrangler build temp
+site/.wrangler/
+data/farms_canonical/
+data/csa_canonical/
+reports/.cache/
+
+# Third-party licensed content — never commit/distribute (IBISWorld license)
+OD6482*.pdf
+
+# NTFS download metadata (WSL)
+*:Zone.Identifier
+
+# Data-viz tooling venv (uv-managed, machine-specific — never commit)
+launch/assets/dataviz/.venv/
+# Third-party academic source PDFs (copyright; CSA substrate papers) — keep local only
+Benefits_of_Nutrition_Educatio.pdf
+Perceived_sustainability_impac.pdf
+Sustainability_as_business_str.pdf
+data/*-bak-pa/
+data/*-bak-sweep/
+*.bak2
+
+# Wrangler build temp (project root)
+.wrangler/
+# Editor/script backups
+*.bak

harvestly-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Harvestly Markets (harvestlymarkets.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE IN OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note: the DATASET this client fetches is licensed separately under CC BY 4.0
+by Harvestly Markets — https://creativecommons.org/licenses/by/4.0/

harvestly-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+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/).

harvestly-0.1.0/README.md

@@ -0,0 +1,62 @@
+# 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/).

harvestly-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "harvestly"
+version = "0.1.0"
+description = "US farmers-market statistics: official Python client for the Harvestly Markets open dataset (CC BY 4.0, USDA-derived)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Quinn Vandt", email = "quinn@harvestlymarkets.com" }]
+keywords = [
+  "farmers-markets", "open-data", "usda", "local-food", "csa",
+  "farm-stands", "dataset", "statistics", "food",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://harvestlymarkets.com"
+Documentation = "https://harvestlymarkets.com/data-sources/"
+"Dataset & methodology" = "https://harvestlymarkets.com/about/methodology/"
+"State statistics" = "https://harvestlymarkets.com/farmers-market-statistics/"
+
+[project.scripts]
+harvestly = "harvestly.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/harvestly"]

harvestly-0.1.0/src/harvestly/__init__.py

@@ -0,0 +1,100 @@
+"""harvestly — official Python client for the Harvestly Markets open dataset.
+
+State-by-state statistics on 8,800+ US farmers markets (plus CSA programs and
+farm stands), cleaned and enriched from the USDA AMS Local Food Portal.
+CC BY 4.0 — https://harvestlymarkets.com/data-sources/
+"""
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import time
+import urllib.request
+
+__version__ = "0.1.0"
+
+DATA_URL = "https://harvestlymarkets.com/data/us-farmers-markets-by-state-2026.json"
+SITE = "https://harvestlymarkets.com"
+CACHE_TTL_SECONDS = 24 * 3600
+_USER_AGENT = f"harvestly-python/{__version__} (+{SITE}/data-sources/)"
+
+
+class Dataset:
+    """The by-state statistics dataset: metadata, national totals, 53 state rows."""
+
+    def __init__(self, metadata: dict, national: dict, states: list):
+        self.metadata = metadata
+        self.national = national
+        self._states = states
+        self._by_key = {}
+        for row in states:
+            self._by_key[row["state_abbr"].lower()] = row
+            self._by_key[row["state_name"].lower()] = row
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Dataset":
+        return cls(d["metadata"], d["national"], d["states"])
+
+    def states(self) -> list:
+        return list(self._states)
+
+    def state(self, key: str) -> dict:
+        try:
+            return self._by_key[key.strip().lower()]
+        except KeyError:
+            raise KeyError(f"unknown state: {key!r} (use a USPS abbreviation or full name)")
+
+    def top(self, metric: str, n: int = 10, ascending: bool = False) -> list:
+        if not self._states or metric not in self._states[0]:
+            valid = ", ".join(k for k in (self._states[0] if self._states else {}))
+            raise ValueError(f"unknown metric: {metric!r} (valid: {valid})")
+        rows = [r for r in self._states if r.get(metric) is not None]
+        return sorted(rows, key=lambda r: r[metric], reverse=not ascending)[:n]
+
+
+def state_url(abbr: str) -> str:
+    """Link to the live state hub (full market listings)."""
+    return f"{SITE}/states/{abbr.strip().lower()}/"
+
+
+def zip_url(zip_code: str) -> str:
+    """Link to the live ZIP market finder."""
+    z = zip_code.strip()
+    if not (len(z) == 5 and z.isdigit()):
+        raise ValueError(f"zip_code must be 5 digits, got {zip_code!r}")
+    return f"{SITE}/zip/{z}/"
+
+
+def _cache_path() -> pathlib.Path:
+    base = os.environ.get("HARVESTLY_CACHE_DIR") or os.path.join(
+        os.environ.get("XDG_CACHE_HOME", os.path.expanduser("~/.cache")), "harvestly"
+    )
+    return pathlib.Path(base) / "dataset.json"
+
+
+def _fetch_remote() -> dict:
+    req = urllib.request.Request(DATA_URL, headers={"User-Agent": _USER_AGENT})
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def load(refresh: bool = False, fetch=None) -> Dataset:
+    """Load the dataset, using a local cache (~24h TTL).
+
+    refresh=True bypasses the cache. `fetch` overrides the HTTP fetcher (testing).
+    """
+    path = _cache_path()
+    if not refresh and path.exists():
+        age = time.time() - path.stat().st_mtime
+        if age < CACHE_TTL_SECONDS:
+            try:
+                return Dataset.from_dict(json.loads(path.read_text()))
+            except (ValueError, KeyError):
+                pass  # corrupt cache — refetch
+    d = (fetch or _fetch_remote)()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(d))
+    tmp.replace(path)
+    return Dataset.from_dict(d)

harvestly-0.1.0/src/harvestly/cli.py

@@ -0,0 +1,82 @@
+"""harvestly CLI — quick lookups from the Harvestly Markets open dataset."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+import harvestly
+
+
+def _fmt_row(row: dict) -> str:
+    return (
+        f"{row['state_name']} ({row['state_abbr']})\n"
+        f"  farmers markets : {row['farmers_markets']:,}\n"
+        f"  CSA programs    : {row['csa_programs']:,}\n"
+        f"  farm stands     : {row['farm_stands']:,}\n"
+        f"  SNAP/EBT        : {row['snap_ebt_markets']:,} ({row['snap_ebt_pct']}%)\n"
+        f"  organic vendors : {row['organic_vendor_markets']:,} ({row['organic_pct']}%)\n"
+        f"  with website    : {row['markets_with_website']:,} ({row['website_pct']}%)\n"
+        f"  browse listings : {harvestly.state_url(row['state_abbr'])}"
+    )
+
+
+def main(argv=None, fetch=None) -> int:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--json", action="store_true", help="emit raw JSON")
+    common.add_argument("--refresh", action="store_true", help="bypass the 24h cache")
+    p = argparse.ArgumentParser(
+        prog="harvestly",
+        description="US farmers-market statistics (CC BY 4.0, harvestlymarkets.com)",
+    )
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sp = sub.add_parser("state", help="one state's statistics", parents=[common])
+    sp.add_argument("name", help="USPS abbreviation or full state name")
+    sub.add_parser("national", help="national totals", parents=[common])
+    tp = sub.add_parser("top", help="rank states by a metric", parents=[common])
+    tp.add_argument("metric", help="e.g. farmers_markets, website_pct, snap_ebt_pct")
+    tp.add_argument("-n", type=int, default=10)
+    tp.add_argument("--ascending", action="store_true")
+    args = p.parse_args(argv)
+
+    ds = harvestly.load(refresh=args.refresh, fetch=fetch)
+
+    if args.cmd == "state":
+        try:
+            row = ds.state(args.name)
+        except KeyError as e:
+            print(e, file=sys.stderr)
+            return 2
+        print(json.dumps(row, indent=2) if args.json else _fmt_row(row))
+    elif args.cmd == "national":
+        if args.json:
+            print(json.dumps(ds.national, indent=2))
+        else:
+            n = ds.national
+            print(
+                f"US totals ({ds.metadata.get('temporal_coverage', '')}): "
+                f"{n['farmers_markets']:,} farmers markets · "
+                f"{n['csa_programs']:,} CSA programs · "
+                f"{n['farm_stands']:,} farm stands\n"
+                f"SNAP/EBT {n['snap_ebt_pct']}% · organic {n['organic_pct']}% · "
+                f"with website {n['website_pct']}%\n"
+                f"source: {ds.metadata.get('url', harvestly.SITE)}"
+            )
+    elif args.cmd == "top":
+        try:
+            rows = ds.top(args.metric, args.n, ascending=args.ascending)
+        except ValueError as e:
+            print(e, file=sys.stderr)
+            return 2
+        if args.json:
+            print(json.dumps(rows, indent=2))
+        else:
+            for i, r in enumerate(rows, 1):
+                print(f"{i:>2}. {r['state_name']:<22} {r[args.metric]:,}"
+                      if isinstance(r[args.metric], int)
+                      else f"{i:>2}. {r['state_name']:<22} {r[args.metric]}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

harvestly-0.1.0/tests/fixture_dataset.json

@@ -0,0 +1,716 @@
+{
+  "metadata": {
+    "title": "US Farmers Markets by State, 2026",
+    "publisher": "Harvestly Markets",
+    "source": "USDA AMS Local Food Portal (https://www.usdalocalfoodportal.com/)",
+    "license": "https://creativecommons.org/licenses/by/4.0/",
+    "license_note": "CC BY 4.0 — free to reuse with attribution to Harvestly Markets.",
+    "attribution": "Harvestly Markets (2026). US Farmers Market Statistics. https://harvestlymarkets.com/farmers-market-statistics/",
+    "temporal_coverage": "2026",
+    "last_updated": "2026-07-08",
+    "url": "https://harvestlymarkets.com/farmers-market-statistics/"
+  },
+  "national": {
+    "farmers_markets": 8863,
+    "csa_programs": 1985,
+    "farm_stands": 7812,
+    "states_and_territories": 52,
+    "snap_ebt_markets": 924,
+    "snap_ebt_pct": 10.4,
+    "organic_vendor_markets": 1063,
+    "organic_pct": 12,
+    "markets_with_website": 4431,
+    "website_pct": 50
+  },
+  "states": [
+    {
+      "state_name": "California",
+      "state_abbr": "CA",
+      "farmers_markets": 679,
+      "csa_programs": 78,
+      "farm_stands": 223,
+      "snap_ebt_markets": 101,
+      "snap_ebt_pct": 14.9,
+      "organic_vendor_markets": 116,
+      "organic_pct": 17.1,
+      "markets_with_website": 275,
+      "website_pct": 40.5
+    },
+    {
+      "state_name": "New York",
+      "state_abbr": "NY",
+      "farmers_markets": 587,
+      "csa_programs": 144,
+      "farm_stands": 272,
+      "snap_ebt_markets": 42,
+      "snap_ebt_pct": 7.2,
+      "organic_vendor_markets": 46,
+      "organic_pct": 7.8,
+      "markets_with_website": 299,
+      "website_pct": 50.9
+    },
+    {
+      "state_name": "Illinois",
+      "state_abbr": "IL",
+      "farmers_markets": 485,
+      "csa_programs": 60,
+      "farm_stands": 713,
+      "snap_ebt_markets": 31,
+      "snap_ebt_pct": 6.4,
+      "organic_vendor_markets": 43,
+      "organic_pct": 8.9,
+      "markets_with_website": 239,
+      "website_pct": 49.3
+    },
+    {
+      "state_name": "Pennsylvania",
+      "state_abbr": "PA",
+      "farmers_markets": 441,
+      "csa_programs": 93,
+      "farm_stands": 886,
+      "snap_ebt_markets": 18,
+      "snap_ebt_pct": 4.1,
+      "organic_vendor_markets": 44,
+      "organic_pct": 10,
+      "markets_with_website": 291,
+      "website_pct": 66
+    },
+    {
+      "state_name": "Minnesota",
+      "state_abbr": "MN",
+      "farmers_markets": 438,
+      "csa_programs": 56,
+      "farm_stands": 80,
+      "snap_ebt_markets": 105,
+      "snap_ebt_pct": 24,
+      "organic_vendor_markets": 14,
+      "organic_pct": 3.2,
+      "markets_with_website": 183,
+      "website_pct": 41.8
+    },
+    {
+      "state_name": "Virginia",
+      "state_abbr": "VA",
+      "farmers_markets": 398,
+      "csa_programs": 78,
+      "farm_stands": 180,
+      "snap_ebt_markets": 22,
+      "snap_ebt_pct": 5.5,
+      "organic_vendor_markets": 28,
+      "organic_pct": 7,
+      "markets_with_website": 231,
+      "website_pct": 58
+    },
+    {
+      "state_name": "Wisconsin",
+      "state_abbr": "WI",
+      "farmers_markets": 356,
+      "csa_programs": 83,
+      "farm_stands": 152,
+      "snap_ebt_markets": 26,
+      "snap_ebt_pct": 7.3,
+      "organic_vendor_markets": 38,
+      "organic_pct": 10.7,
+      "markets_with_website": 238,
+      "website_pct": 66.9
+    },
+    {
+      "state_name": "Michigan",
+      "state_abbr": "MI",
+      "farmers_markets": 336,
+      "csa_programs": 96,
+      "farm_stands": 253,
+      "snap_ebt_markets": 38,
+      "snap_ebt_pct": 11.3,
+      "organic_vendor_markets": 42,
+      "organic_pct": 12.5,
+      "markets_with_website": 152,
+      "website_pct": 45.2
+    },
+    {
+      "state_name": "Ohio",
+      "state_abbr": "OH",
+      "farmers_markets": 283,
+      "csa_programs": 41,
+      "farm_stands": 582,
+      "snap_ebt_markets": 17,
+      "snap_ebt_pct": 6,
+      "organic_vendor_markets": 15,
+      "organic_pct": 5.3,
+      "markets_with_website": 134,
+      "website_pct": 47.3
+    },
+    {
+      "state_name": "Missouri",
+      "state_abbr": "MO",
+      "farmers_markets": 275,
+      "csa_programs": 27,
+      "farm_stands": 105,
+      "snap_ebt_markets": 12,
+      "snap_ebt_pct": 4.4,
+      "organic_vendor_markets": 16,
+      "organic_pct": 5.8,
+      "markets_with_website": 187,
+      "website_pct": 68
+    },
+    {
+      "state_name": "Colorado",
+      "state_abbr": "CO",
+      "farmers_markets": 267,
+      "csa_programs": 50,
+      "farm_stands": 69,
+      "snap_ebt_markets": 16,
+      "snap_ebt_pct": 6,
+      "organic_vendor_markets": 16,
+      "organic_pct": 6,
+      "markets_with_website": 174,
+      "website_pct": 65.2
+    },
+    {
+      "state_name": "Florida",
+      "state_abbr": "FL",
+      "farmers_markets": 262,
+      "csa_programs": 42,
+      "farm_stands": 203,
+      "snap_ebt_markets": 15,
+      "snap_ebt_pct": 5.7,
+      "organic_vendor_markets": 22,
+      "organic_pct": 8.4,
+      "markets_with_website": 143,
+      "website_pct": 54.6
+    },
+    {
+      "state_name": "Massachusetts",
+      "state_abbr": "MA",
+      "farmers_markets": 249,
+      "csa_programs": 67,
+      "farm_stands": 79,
+      "snap_ebt_markets": 33,
+      "snap_ebt_pct": 13.3,
+      "organic_vendor_markets": 34,
+      "organic_pct": 13.7,
+      "markets_with_website": 229,
+      "website_pct": 92
+    },
+    {
+      "state_name": "Georgia",
+      "state_abbr": "GA",
+      "farmers_markets": 247,
+      "csa_programs": 32,
+      "farm_stands": 95,
+      "snap_ebt_markets": 27,
+      "snap_ebt_pct": 10.9,
+      "organic_vendor_markets": 29,
+      "organic_pct": 11.7,
+      "markets_with_website": 105,
+      "website_pct": 42.5
+    },
+    {
+      "state_name": "Texas",
+      "state_abbr": "TX",
+      "farmers_markets": 231,
+      "csa_programs": 46,
+      "farm_stands": 145,
+      "snap_ebt_markets": 29,
+      "snap_ebt_pct": 12.6,
+      "organic_vendor_markets": 40,
+      "organic_pct": 17.3,
+      "markets_with_website": 80,
+      "website_pct": 34.6
+    },
+    {
+      "state_name": "North Carolina",
+      "state_abbr": "NC",
+      "farmers_markets": 211,
+      "csa_programs": 61,
+      "farm_stands": 660,
+      "snap_ebt_markets": 37,
+      "snap_ebt_pct": 17.5,
+      "organic_vendor_markets": 34,
+      "organic_pct": 16.1,
+      "markets_with_website": 75,
+      "website_pct": 35.5
+    },
+    {
+      "state_name": "Kentucky",
+      "state_abbr": "KY",
+      "farmers_markets": 191,
+      "csa_programs": 25,
+      "farm_stands": 63,
+      "snap_ebt_markets": 22,
+      "snap_ebt_pct": 11.5,
+      "organic_vendor_markets": 71,
+      "organic_pct": 37.2,
+      "markets_with_website": 31,
+      "website_pct": 16.2
+    },
+    {
+      "state_name": "Indiana",
+      "state_abbr": "IN",
+      "farmers_markets": 190,
+      "csa_programs": 37,
+      "farm_stands": 147,
+      "snap_ebt_markets": 24,
+      "snap_ebt_pct": 12.6,
+      "organic_vendor_markets": 47,
+      "organic_pct": 24.7,
+      "markets_with_website": 62,
+      "website_pct": 32.6
+    },
+    {
+      "state_name": "Iowa",
+      "state_abbr": "IA",
+      "farmers_markets": 157,
+      "csa_programs": 41,
+      "farm_stands": 56,
+      "snap_ebt_markets": 21,
+      "snap_ebt_pct": 13.4,
+      "organic_vendor_markets": 22,
+      "organic_pct": 14,
+      "markets_with_website": 71,
+      "website_pct": 45.2
+    },
+    {
+      "state_name": "Washington",
+      "state_abbr": "WA",
+      "farmers_markets": 154,
+      "csa_programs": 67,
+      "farm_stands": 156,
+      "snap_ebt_markets": 28,
+      "snap_ebt_pct": 18.2,
+      "organic_vendor_markets": 26,
+      "organic_pct": 16.9,
+      "markets_with_website": 48,
+      "website_pct": 31.2
+    },
+    {
+      "state_name": "Maryland",
+      "state_abbr": "MD",
+      "farmers_markets": 151,
+      "csa_programs": 59,
+      "farm_stands": 54,
+      "snap_ebt_markets": 7,
+      "snap_ebt_pct": 4.6,
+      "organic_vendor_markets": 14,
+      "organic_pct": 9.3,
+      "markets_with_website": 87,
+      "website_pct": 57.6
+    },
+    {
+      "state_name": "Connecticut",
+      "state_abbr": "CT",
+      "farmers_markets": 138,
+      "csa_programs": 38,
+      "farm_stands": 167,
+      "snap_ebt_markets": 11,
+      "snap_ebt_pct": 8,
+      "organic_vendor_markets": 10,
+      "organic_pct": 7.2,
+      "markets_with_website": 68,
+      "website_pct": 49.3
+    },
+    {
+      "state_name": "Kansas",
+      "state_abbr": "KS",
+      "farmers_markets": 129,
+      "csa_programs": 11,
+      "farm_stands": 51,
+      "snap_ebt_markets": 11,
+      "snap_ebt_pct": 8.5,
+      "organic_vendor_markets": 17,
+      "organic_pct": 13.2,
+      "markets_with_website": 58,
+      "website_pct": 45
+    },
+    {
+      "state_name": "Delaware",
+      "state_abbr": "DE",
+      "farmers_markets": 122,
+      "csa_programs": 5,
+      "farm_stands": 14,
+      "snap_ebt_markets": 4,
+      "snap_ebt_pct": 3.3,
+      "organic_vendor_markets": 5,
+      "organic_pct": 4.1,
+      "markets_with_website": 111,
+      "website_pct": 91
+    },
+    {
+      "state_name": "Alabama",
+      "state_abbr": "AL",
+      "farmers_markets": 118,
+      "csa_programs": 11,
+      "farm_stands": 69,
+      "snap_ebt_markets": 1,
+      "snap_ebt_pct": 0.8,
+      "organic_vendor_markets": 5,
+      "organic_pct": 4.2,
+      "markets_with_website": 30,
+      "website_pct": 25.4
+    },
+    {
+      "state_name": "Oklahoma",
+      "state_abbr": "OK",
+      "farmers_markets": 109,
+      "csa_programs": 10,
+      "farm_stands": 23,
+      "snap_ebt_markets": 10,
+      "snap_ebt_pct": 9.2,
+      "organic_vendor_markets": 4,
+      "organic_pct": 3.7,
+      "markets_with_website": 42,
+      "website_pct": 38.5
+    },
+    {
+      "state_name": "Arizona",
+      "state_abbr": "AZ",
+      "farmers_markets": 103,
+      "csa_programs": 16,
+      "farm_stands": 20,
+      "snap_ebt_markets": 4,
+      "snap_ebt_pct": 3.9,
+      "organic_vendor_markets": 7,
+      "organic_pct": 6.8,
+      "markets_with_website": 41,
+      "website_pct": 39.8
+    },
+    {
+      "state_name": "Oregon",
+      "state_abbr": "OR",
+      "farmers_markets": 101,
+      "csa_programs": 58,
+      "farm_stands": 142,
+      "snap_ebt_markets": 42,
+      "snap_ebt_pct": 41.6,
+      "organic_vendor_markets": 39,
+      "organic_pct": 38.6,
+      "markets_with_website": 65,
+      "website_pct": 64.4
+    },
+    {
+      "state_name": "Tennessee",
+      "state_abbr": "TN",
+      "farmers_markets": 99,
+      "csa_programs": 34,
+      "farm_stands": 293,
+      "snap_ebt_markets": 12,
+      "snap_ebt_pct": 12.1,
+      "organic_vendor_markets": 17,
+      "organic_pct": 17.2,
+      "markets_with_website": 55,
+      "website_pct": 55.6
+    },
+    {
+      "state_name": "South Carolina",
+      "state_abbr": "SC",
+      "farmers_markets": 93,
+      "csa_programs": 13,
+      "farm_stands": 123,
+      "snap_ebt_markets": 18,
+      "snap_ebt_pct": 19.4,
+      "organic_vendor_markets": 19,
+      "organic_pct": 20.4,
+      "markets_with_website": 40,
+      "website_pct": 43
+    },
+    {
+      "state_name": "New Jersey",
+      "state_abbr": "NJ",
+      "farmers_markets": 87,
+      "csa_programs": 42,
+      "farm_stands": 109,
+      "snap_ebt_markets": 19,
+      "snap_ebt_pct": 21.8,
+      "organic_vendor_markets": 24,
+      "organic_pct": 27.6,
+      "markets_with_website": 37,
+      "website_pct": 42.5
+    },
+    {
+      "state_name": "Montana",
+      "state_abbr": "MT",
+      "farmers_markets": 80,
+      "csa_programs": 10,
+      "farm_stands": 468,
+      "snap_ebt_markets": 6,
+      "snap_ebt_pct": 7.5,
+      "organic_vendor_markets": 6,
+      "organic_pct": 7.5,
+      "markets_with_website": 12,
+      "website_pct": 15
+    },
+    {
+      "state_name": "Vermont",
+      "state_abbr": "VT",
+      "farmers_markets": 78,
+      "csa_programs": 28,
+      "farm_stands": 66,
+      "snap_ebt_markets": 10,
+      "snap_ebt_pct": 12.8,
+      "organic_vendor_markets": 11,
+      "organic_pct": 14.1,
+      "markets_with_website": 24,
+      "website_pct": 30.8
+    },
+    {
+      "state_name": "Alaska",
+      "state_abbr": "AK",
+      "farmers_markets": 69,
+      "csa_programs": 6,
+      "farm_stands": 8,
+      "snap_ebt_markets": 3,
+      "snap_ebt_pct": 4.3,
+      "organic_vendor_markets": 4,
+      "organic_pct": 5.8,
+      "markets_with_website": 49,
+      "website_pct": 71
+    },
+    {
+      "state_name": "Arkansas",
+      "state_abbr": "AR",
+      "farmers_markets": 67,
+      "csa_programs": 7,
+      "farm_stands": 65,
+      "snap_ebt_markets": 9,
+      "snap_ebt_pct": 13.4,
+      "organic_vendor_markets": 20,
+      "organic_pct": 29.9,
+      "markets_with_website": 24,
+      "website_pct": 35.8
+    },
+    {
+      "state_name": "Louisiana",
+      "state_abbr": "LA",
+      "farmers_markets": 64,
+      "csa_programs": 4,
+      "farm_stands": 108,
+      "snap_ebt_markets": 11,
+      "snap_ebt_pct": 17.2,
+      "organic_vendor_markets": 12,
+      "organic_pct": 18.8,
+      "markets_with_website": 34,
+      "website_pct": 53.1
+    },
+    {
+      "state_name": "Wyoming",
+      "state_abbr": "WY",
+      "farmers_markets": 61,
+      "csa_programs": 5,
+      "farm_stands": 11,
+      "snap_ebt_markets": 1,
+      "snap_ebt_pct": 1.6,
+      "organic_vendor_markets": 3,
+      "organic_pct": 4.9,
+      "markets_with_website": 17,
+      "website_pct": 27.9
+    },
+    {
+      "state_name": "West Virginia",
+      "state_abbr": "WV",
+      "farmers_markets": 59,
+      "csa_programs": 4,
+      "farm_stands": 333,
+      "snap_ebt_markets": 6,
+      "snap_ebt_pct": 10.2,
+      "organic_vendor_markets": 5,
+      "organic_pct": 8.5,
+      "markets_with_website": 22,
+      "website_pct": 37.3
+    },
+    {
+      "state_name": "New Hampshire",
+      "state_abbr": "NH",
+      "farmers_markets": 53,
+      "csa_programs": 36,
+      "farm_stands": 140,
+      "snap_ebt_markets": 6,
+      "snap_ebt_pct": 11.3,
+      "organic_vendor_markets": 6,
+      "organic_pct": 11.3,
+      "markets_with_website": 32,
+      "website_pct": 60.4
+    },
+    {
+      "state_name": "Mississippi",
+      "state_abbr": "MS",
+      "farmers_markets": 52,
+      "csa_programs": 5,
+      "farm_stands": 25,
+      "snap_ebt_markets": 2,
+      "snap_ebt_pct": 3.8,
+      "organic_vendor_markets": 2,
+      "organic_pct": 3.8,
+      "markets_with_website": 17,
+      "website_pct": 32.7
+    },
+    {
+      "state_name": "Maine",
+      "state_abbr": "ME",
+      "farmers_markets": 44,
+      "csa_programs": 29,
+      "farm_stands": 80,
+      "snap_ebt_markets": 5,
+      "snap_ebt_pct": 11.4,
+      "organic_vendor_markets": 5,
+      "organic_pct": 11.4,
+      "markets_with_website": 22,
+      "website_pct": 50
+    },
+    {
+      "state_name": "Nebraska",
+      "state_abbr": "NE",
+      "farmers_markets": 42,
+      "csa_programs": 10,
+      "farm_stands": 16,
+      "snap_ebt_markets": 2,
+      "snap_ebt_pct": 4.8,
+      "organic_vendor_markets": 19,
+      "organic_pct": 45.2,
+      "markets_with_website": 11,
+      "website_pct": 26.2
+    },
+    {
+      "state_name": "New Mexico",
+      "state_abbr": "NM",
+      "farmers_markets": 39,
+      "csa_programs": 3,
+      "farm_stands": 25,
+      "snap_ebt_markets": 4,
+      "snap_ebt_pct": 10.3,
+      "organic_vendor_markets": 5,
+      "organic_pct": 12.8,
+      "markets_with_website": 8,
+      "website_pct": 20.5
+    },
+    {
+      "state_name": "Idaho",
+      "state_abbr": "ID",
+      "farmers_markets": 38,
+      "csa_programs": 16,
+      "farm_stands": 175,
+      "snap_ebt_markets": 7,
+      "snap_ebt_pct": 18.4,
+      "organic_vendor_markets": 8,
+      "organic_pct": 21.1,
+      "markets_with_website": 29,
+      "website_pct": 76.3
+    },
+    {
+      "state_name": "Rhode Island",
+      "state_abbr": "RI",
+      "farmers_markets": 32,
+      "csa_programs": 7,
+      "farm_stands": 22,
+      "snap_ebt_markets": 21,
+      "snap_ebt_pct": 65.6,
+      "organic_vendor_markets": 25,
+      "organic_pct": 78.1,
+      "markets_with_website": 21,
+      "website_pct": 65.6
+    },
+    {
+      "state_name": "Nevada",
+      "state_abbr": "NV",
+      "farmers_markets": 31,
+      "csa_programs": 2,
+      "farm_stands": 14,
+      "snap_ebt_markets": 5,
+      "snap_ebt_pct": 16.1,
+      "organic_vendor_markets": 5,
+      "organic_pct": 16.1,
+      "markets_with_website": 11,
+      "website_pct": 35.5
+    },
+    {
+      "state_name": "District Of Columbia",
+      "state_abbr": "DC",
+      "farmers_markets": 28,
+      "csa_programs": 0,
+      "farm_stands": 0,
+      "snap_ebt_markets": 5,
+      "snap_ebt_pct": 17.9,
+      "organic_vendor_markets": 5,
+      "organic_pct": 17.9,
+      "markets_with_website": 10,
+      "website_pct": 35.7
+    },
+    {
+      "state_name": "South Dakota",
+      "state_abbr": "SD",
+      "farmers_markets": 18,
+      "csa_programs": 10,
+      "farm_stands": 16,
+      "snap_ebt_markets": 1,
+      "snap_ebt_pct": 5.6,
+      "organic_vendor_markets": 1,
+      "organic_pct": 5.6,
+      "markets_with_website": 4,
+      "website_pct": 22.2
+    },
+    {
+      "state_name": "Utah",
+      "state_abbr": "UT",
+      "farmers_markets": 16,
+      "csa_programs": 12,
+      "farm_stands": 40,
+      "snap_ebt_markets": 5,
+      "snap_ebt_pct": 31.3,
+      "organic_vendor_markets": 2,
+      "organic_pct": 12.5,
+      "markets_with_website": 12,
+      "website_pct": 75
+    },
+    {
+      "state_name": "Hawaii",
+      "state_abbr": "HI",
+      "farmers_markets": 13,
+      "csa_programs": 11,
+      "farm_stands": 5,
+      "snap_ebt_markets": 5,
+      "snap_ebt_pct": 38.5,
+      "organic_vendor_markets": 6,
+      "organic_pct": 46.2,
+      "markets_with_website": 8,
+      "website_pct": 61.5
+    },
+    {
+      "state_name": "North Dakota",
+      "state_abbr": "ND",
+      "farmers_markets": 7,
+      "csa_programs": 6,
+      "farm_stands": 9,
+      "snap_ebt_markets": 2,
+      "snap_ebt_pct": 28.6,
+      "organic_vendor_markets": 4,
+      "organic_pct": 57.1,
+      "markets_with_website": 2,
+      "website_pct": 28.6
+    },
+    {
+      "state_name": "Puerto Rico",
+      "state_abbr": "PR",
+      "farmers_markets": 2,
+      "csa_programs": 0,
+      "farm_stands": 1,
+      "snap_ebt_markets": 0,
+      "snap_ebt_pct": 0,
+      "organic_vendor_markets": 2,
+      "organic_pct": 100,
+      "markets_with_website": 1,
+      "website_pct": 50
+    },
+    {
+      "state_name": "Virgin Islands",
+      "state_abbr": "VI",
+      "farmers_markets": 0,
+      "csa_programs": 0,
+      "farm_stands": 1,
+      "snap_ebt_markets": 0,
+      "snap_ebt_pct": 0,
+      "organic_vendor_markets": 0,
+      "organic_pct": 0,
+      "markets_with_website": 0,
+      "website_pct": 0
+    }
+  ]
+}

harvestly-0.1.0/tests/test_harvestly.py

@@ -0,0 +1,159 @@
+"""Offline tests for the harvestly client — fixture is the real production schema."""
+import io
+import json
+import os
+import pathlib
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+
+import harvestly
+from harvestly import Dataset, cli
+
+FIXTURE = pathlib.Path(__file__).parent / "fixture_dataset.json"
+
+
+def fixture_dict():
+    return json.loads(FIXTURE.read_text())
+
+
+class TestDataset(unittest.TestCase):
+    def setUp(self):
+        self.ds = Dataset.from_dict(fixture_dict())
+
+    def test_states_returns_all_rows(self):
+        rows = self.ds.states()
+        self.assertEqual(len(rows), 53)
+        self.assertIn("state_abbr", rows[0])
+
+    def test_state_lookup_by_abbr_case_insensitive(self):
+        row = self.ds.state("ca")
+        self.assertEqual(row["state_name"], "California")
+        self.assertEqual(row["farmers_markets"], 679)
+        self.assertEqual(self.ds.state("CA"), row)
+
+    def test_state_lookup_by_full_name(self):
+        row = self.ds.state("California")
+        self.assertEqual(row["state_abbr"], "CA")
+
+    def test_state_unknown_raises_keyerror(self):
+        with self.assertRaises(KeyError):
+            self.ds.state("zz")
+
+    def test_national_block(self):
+        self.assertEqual(self.ds.national["farmers_markets"], 8863)
+
+    def test_metadata_carries_license_and_attribution(self):
+        self.assertIn("creativecommons.org/licenses/by/4.0", self.ds.metadata["license"])
+        self.assertIn("harvestlymarkets.com", self.ds.metadata["attribution"])
+
+    def test_top_sorts_descending_by_default(self):
+        top3 = self.ds.top("farmers_markets", 3)
+        self.assertEqual(top3[0]["state_abbr"], "CA")
+        vals = [r["farmers_markets"] for r in top3]
+        self.assertEqual(vals, sorted(vals, reverse=True))
+
+    def test_top_ascending(self):
+        bottom = self.ds.top("farmers_markets", 3, ascending=True)
+        vals = [r["farmers_markets"] for r in bottom]
+        self.assertEqual(vals, sorted(vals))
+
+    def test_top_unknown_metric_raises_valueerror(self):
+        with self.assertRaises(ValueError):
+            self.ds.top("nonsense_metric", 3)
+
+
+class TestUrls(unittest.TestCase):
+    def test_state_url(self):
+        self.assertEqual(
+            harvestly.state_url("ny"), "https://harvestlymarkets.com/states/ny/"
+        )
+
+    def test_zip_url(self):
+        self.assertEqual(
+            harvestly.zip_url("12180"), "https://harvestlymarkets.com/zip/12180/"
+        )
+
+    def test_zip_url_rejects_non_5_digit(self):
+        with self.assertRaises(ValueError):
+            harvestly.zip_url("1218")
+
+
+class TestLoadCache(unittest.TestCase):
+    def test_load_fetches_once_then_reads_cache(self):
+        calls = []
+
+        def fake_fetch():
+            calls.append(1)
+            return fixture_dict()
+
+        with tempfile.TemporaryDirectory() as tmp:
+            os.environ["HARVESTLY_CACHE_DIR"] = tmp
+            try:
+                ds1 = harvestly.load(fetch=fake_fetch)
+                ds2 = harvestly.load(fetch=fake_fetch)
+            finally:
+                del os.environ["HARVESTLY_CACHE_DIR"]
+        self.assertEqual(len(calls), 1)
+        self.assertEqual(ds1.national, ds2.national)
+
+    def test_load_refresh_true_refetches(self):
+        calls = []
+
+        def fake_fetch():
+            calls.append(1)
+            return fixture_dict()
+
+        with tempfile.TemporaryDirectory() as tmp:
+            os.environ["HARVESTLY_CACHE_DIR"] = tmp
+            try:
+                harvestly.load(fetch=fake_fetch)
+                harvestly.load(fetch=fake_fetch, refresh=True)
+            finally:
+                del os.environ["HARVESTLY_CACHE_DIR"]
+        self.assertEqual(len(calls), 2)
+
+
+class TestCli(unittest.TestCase):
+    def run_cli(self, *argv):
+        def fake_fetch():
+            return fixture_dict()
+
+        buf = io.StringIO()
+        with tempfile.TemporaryDirectory() as tmp:
+            os.environ["HARVESTLY_CACHE_DIR"] = tmp
+            try:
+                with redirect_stdout(buf):
+                    rc = cli.main(list(argv), fetch=fake_fetch)
+            finally:
+                del os.environ["HARVESTLY_CACHE_DIR"]
+        return rc, buf.getvalue()
+
+    def test_cli_state(self):
+        rc, out = self.run_cli("state", "ca")
+        self.assertEqual(rc, 0)
+        self.assertIn("California", out)
+        self.assertIn("679", out)
+
+    def test_cli_national(self):
+        rc, out = self.run_cli("national")
+        self.assertEqual(rc, 0)
+        self.assertIn("8,863", out)
+
+    def test_cli_top(self):
+        rc, out = self.run_cli("top", "website_pct", "-n", "3")
+        self.assertEqual(rc, 0)
+        self.assertEqual(len([l for l in out.splitlines() if l.strip()]) >= 3, True)
+
+    def test_cli_json_flag_emits_valid_json(self):
+        rc, out = self.run_cli("state", "vt", "--json")
+        self.assertEqual(rc, 0)
+        self.assertEqual(json.loads(out)["state_abbr"], "VT")
+
+    def test_cli_unknown_state_returns_nonzero(self):
+        rc, out = self.run_cli("state", "zz")
+        self.assertNotEqual(rc, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()