API Reference

Documentation for all exported functions in USDAQuickStats.jl.

API Key Management

USDAQuickStats.set_api_key — Function
set_api_key(api_key::String; overwrite::Bool=false)

Set the USDA NASS Quick Stats API key as an environment variable for the current Julia session.

The API key must be a 36-character UUID string. You can request a key at https://quickstats.nass.usda.gov/api.

Arguments

  • api_key::String: Your USDA NASS API key (36-character UUID format).

Keywords

  • overwrite::Bool=false: If true, allows replacing an already-registered key.

Examples

set_api_key("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")

# Overwrite an existing key
set_api_key("bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"; overwrite=true)
source
USDAQuickStats.get_api_key — Function
get_api_key() -> String

Return the currently set USDA NASS API key, or throw an informative error if none has been set.

Examples

get_api_key()
source

Database Queries

USDAQuickStats.get_nass — Function
get_nass(args...; format="json") -> Vector{UInt8}

Query the USDA NASS Quick Stats database and return the raw response body as bytes. The caller is responsible for parsing the result using their preferred packages.

Each argument is a "field=VALUE" string. Spaces in values are handled automatically — no need for %20.

Note: the API has a limit of 50,000 records per query. Use get_counts first to verify your query is within the limit.

Arguments

  • args...: Query parameters as "field=VALUE" strings.

Keywords

  • format::String="json": Response format, one of "json", "csv", "xml".

Examples

# JSON (default) — parse with JSON3
using JSON3, JSONTables, DataFrames
data = get_nass("source_desc=SURVEY", "commodity_desc=ORANGES", "state_alpha=CA", "year=2019")
df = DataFrame(jsontable(JSON3.read(data).data))

# CSV — parse with CSV.jl
using CSV, DataFrames
data = get_nass("commodity_desc=ORANGES", "state_alpha=CA"; format="csv")
df = CSV.read(data, DataFrame)

# Save raw response to disk
write("output.json", get_nass("commodity_desc=ORANGES"))
source
USDAQuickStats.get_counts — Function
get_counts(args...) -> Int

Return the number of records that a query with the given parameters would return, without actually fetching the data. Useful for checking whether a query would exceed the 50,000 record limit imposed by the USDA NASS API.

Each argument is a "field=VALUE" string. Spaces in values are handled automatically — no need for %20.

Arguments

  • args...: Query parameters as "field=VALUE" strings.

Examples

get_counts("source_desc=SURVEY", "commodity_desc=ORANGES", "state_alpha=CA", "year=2019")
source
USDAQuickStats.get_param_values — Function
get_param_values(field::String) -> Vector{String}

Return all valid values for a given database field. Useful for exploring what values are available before constructing a query.

Arguments

  • field::String: The name of the database field to query (e.g. "sector_desc").

Examples

get_param_values("sector_desc")
get_param_values("commodity_desc")
source

DataFrames Extension

The following function is only available when DataFrames, JSON3, JSONTables, and CSV are loaded:

USDAQuickStats.get_nass_df — Function
get_nass_df(args...; format="json") -> DataFrame

Query the USDA NASS Quick Stats database and return the results as a DataFrame directly. Available when DataFrames, JSON3, JSONTables, and CSV are loaded.

Supports "json" and "csv" formats. XML is not supported and will throw an ArgumentError.

See get_nass for full documentation of query parameters.

Examples

using USDAQuickStats, DataFrames

df = get_nass_df("commodity_desc=ORANGES", "state_alpha=CA", "year=2019")
source