Metadata-Version: 2.4
Name: fastagsdata
Version: 0.1.1
Summary: Python client for FastAgsData — single source for cleaned alternative ags data
Author-email: FastAgsData <support@fastagsdata.com>
License-Expression: MIT
Project-URL: Homepage, https://fastagsdata.com
Project-URL: Documentation, https://fastagsdata.com/docs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: pyarrow
Requires-Dist: pandas
Dynamic: license-file

# fastagsdata

Single source for cleaned alternative ags data.

Python client for the [FastAgsData](https://fastagsdata.com) API — cleaned USDA agricultural fundamentals delivered as pandas DataFrames.

## Install

```bash
pip install fastagsdata
```

## Quick start

```python
import fastagsdata as fdata

fdata.set_key('your-api-key')

# Get WASDE corn ending stocks
df = fdata.get('wasde', comdty='c', param='stx')

# Get NASS yields for Illinois
df = fdata.get('nass', comdty='c', param='yld', shape_id='us.il')

# Multiple commodities and years
df = fdata.get('wasde', comdty=['c', 's', 'w'], year=[2023, 2024])

# Wildcard params
df = fdata.get('nass', comdty='c', param='prg%')
```

## API key

Set your key in one of three ways:

```python
# 1. Set globally
fdata.set_key('your-api-key')

# 2. Environment variable
export FASTAGSDATA_API_KEY=your-api-key

# 3. Per-request
df = fdata.get('wasde', api_key='your-api-key')
```

Get your API key at [fastagsdata.com](https://fastagsdata.com).

## Parameters

| Parameter  | Description | Example |
|------------|-------------|---------|
| `source`   | Data source | `wasde`, `nass`, `nass_txt`, `fgis_ams`, `flashsale_url`, `exportsales_api`, `exportsales_weeklysummary` |
| `comdty`   | Commodity   | `c`, `s`, `w`, `w.win`, `w.spr`, `b`, `sg`, `fs`, `mx`, `o`, `ry`, `sf` |
| `param`    | Parameter   | `yld`, `ap`, `stx`, `prg%` (supports `%` wildcards) |
| `shape_id` | Geography   | `us`, `us.il`, `us.ia` |
| `shape_lvl`| Administrative level | `0` (national), `1` (state), `2` (county) |
| `year`     | Matches source, generally marketing year | `2024`, `[2023, 2024]` |

All parameters support comma-separated strings or Python lists.

## Sources

| Source | Description | Link | Parameters |
|--------|-------------|------|------------|
| `wasde` | World Agricultural Supply and Demand Estimates. Monthly balance sheet projections for major crops. | [USDA WASDE](https://www.usda.gov/oce/commodity/wasde) | `stx` (ending stocks), `prd` (production), `yld` (yield), `ap` (area planted), `ah` (area harvested), and more |
| `nass` | Final values from NASS QuickStats. No revision history — always reflects the latest number. Updated day after each text release. | [USDA QuickStats](https://quickstats.nass.usda.gov/) | `yld`, `ap`, `ah`, `prd`, `stx`, `prg%` (crop progress) |
| `nass_txt` | Parsed directly from NASS text releases. Available on release day and preserves revision history across subsequent releases. | [USDA NASS](https://www.nass.usda.gov/) | Same as `nass` |
| `fgis_ams` | Weekly grain inspections for export. Parsed from AMS website. | [USDA AMS](https://www.ams.usda.gov/) | `inspc` (inspections) |
| `flashsale_url` | Large single-day export sales reported under daily reporting requirements. | [USDA FAS](https://www.fas.usda.gov/) | `flash_sales` |
| `exportsales_api` | Weekly export sales and shipments by commodity and destination. | [USDA FAS](https://apps.fas.usda.gov/esrquery/) | `net_sales`, `exports`, `outstanding` |
| `exportsales_weeklysummary` | Weekly export sales summary totals. | [USDA FAS](https://apps.fas.usda.gov/esrquery/) | `net_sales`, `exports`, `outstanding` |

> **Note:** Not all commodity/param combinations from QuickStats are currently saved. If you need a combination that isn't available, reach out to support@fastagsdata.com and it will be added within 24 hours.

> **Note:** Not all NASS text reports are currently being parsed. To request additional reports, reach out to support@fastagsdata.com.

## Response

Returns a pandas DataFrame with columns: `date_ref`, `date_release`, `source`, `comdty`, `shape_id`, `param`, `value`, `year`. Date columns are `datetime64` type.
