usda-fas-sdk 0.1.11

Python SDK for USDA FAS Open Data API

USDA FAS Open Data SDK (Python)

A powerful, Pythonic SDK for the USDA Foreign Agricultural Service (FAS) Open Data API. This library provides easy access to vast agricultural data sets including Export Sales, Global Trade, and Production/Supply/Distribution data.

Source Data: USDA FAS Open Data

Data Sets Available

• ESR (Export Sales Reporting): Weekly U.S. export sales of agricultural commodities.
• GATS (Global Agricultural Trade System): U.S. Census and UN ComTrade import/export data.
• PSD (Production, Supply and Distribution): Official USDA forecasts for world agricultural commodities.

Features

• Auth Handling: Seamless integration with USDA FAS API keys.
• Easy Mode: USDAFASEasyClient automatically normalizes data, replacing numeric codes (e.g., CountryCode: 2010) with readable names and descriptions (e.g., Name: Mexico, Genc: MEX).
• Complete Coverage: Support for all endpoints defined in the official Swagger spec.
• Type Hints: Fully typed for better IDE support.

Prerequisites

You need a USDA FAS API Key to use this SDK.

1. Go to the USDA FAS Open Data Portal.
2. Register or Login.
3. Navigate to the "API Keys" section to generate your key.

Installation

pip install usda-fas-sdk

Quick Start

1. Configure Authentication

We recommend using a .env file to keep your API key secure.

Step 1: Create a file named .env in your project root:

USDA_FAS_API_KEY=your_actual_api_key_here

Step 2: Use the SDK

from usda_fas import USDAFASEasyClient
import json

# Automatically loads USDA_FAS_API_KEY from environment or .env
client = USDAFASEasyClient()

# Example: Get Normalized Export Sales Data for Wheat (Code 301) in 2024
data = client.get_esr_exports_normalized(commodity_code=301, market_year=2024)

if data:
    # Print the first enriched record
    print(json.dumps(data[0], indent=2))

Output Example:

{
  "commodityCode": 301,
  "countryCode": 5800,
  "weeklyExports": 0,
  "accumulatedExports": 0,
  "outstandingSales": 1323,
  "grossNewSales": 1323,
  "currentMYNetSales": 0,
  "currentMYTotalCommitment": 1323,
  "nextMYOutstandingSales": 0,
  "nextMYNetSales": 0,
  "unitId": 1,
  "weekEndingDate": "2023-06-01T00:00:00",
  "countryName": "KOR REP ",
  "countryDescription": "KOREA, REPUBLIC OF             ",
  "gencCode": null,
  "regionName": "OTHER ASIA AND OCEANIA        ",
  "commodityName": "Barley",
  "unitName": "Metric Tons"
}

2. Manual Configuration (Alternative)

You can also pass the key directly (not recommended for production code):

client = USDAFASEasyClient(api_key="your_api_key_string")

Advanced Usage

Accessing Raw Clients

If you prefer raw data or specific client separation, you can access the individual clients:

from usda_fas import ESRClient, GATSClient, PSDClient

esr = ESRClient() # Uses env var
raw_commodities = esr.get_esr_commodities()

Contributing

1. Fork the repo.
2. Install dependencies: pip install -r requirements.txt.
3. Submit a Pull Request.

License

MIT