United States Department of Agriculture

United States Department of Agriculture Metadata API

Available years, states, reports, and variables

GitHub OpenAPI

Operations 5

GET /year Get Available Survey Years #
GET /state Get Available States #
GET /report Get Available Reports #
GET /variable Get Available Variables #
GET /get_param_values/ Get Valid Parameter Values #

Documentation

📖
Documentation
https://fdc.nal.usda.gov/api-guide/
📖
Documentation
https://quickstats.nass.usda.gov/api
📖
Documentation
https://www.ers.usda.gov/developer/data-apis/arms-data-api
📖
Documentation
https://www.nrcs.usda.gov/sites/default/files/2023-03/AWDB%20Web%20Service%20User%20Guide.pdf

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/united-states-department-of-agriculture/refs/heads/main/openapi/united-states-department-of-agriculture-metadata-api-openapi.yml

Other Resources

🔗
SpectralRules
https://raw.githubusercontent.com/api-evangelist/united-states-department-of-agriculture/refs/heads/main/rules/usda-fooddata-central-rules.yml
🔗
Signup
https://fdc.nal.usda.gov/api-key-signup/
🔗
Portal
https://www.nass.usda.gov/developer/index.php
🔗
Portal
https://www.ers.usda.gov/developer/data-apis/
🔗
SwaggerUI
https://wcc.sc.egov.usda.gov/awdbRestApi/swagger-ui/index.html

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/united-states-department-of-agriculture-metadata-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

united-states-department-of-agriculture-metadata-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: United States Department Of Agriculture Metadata API
  version: 1.0.0
  license:
    name: Public Domain
    url: https://www.usa.gov/government-works
  description: 'Operations tagged Metadata across 2 of this provider''s published API definitions: usda-ers-arms-openapi.yml, usda-nass-quickstats-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.ers.usda.gov/data/arms
  description: USDA ERS ARMS Data API
- url: https://quickstats.nass.usda.gov/api
  description: USDA NASS Quick Stats API
tags:
- name: Metadata
  description: Available years, states, reports, and variables
paths:
  /year:
    get:
      operationId: getAvailableYears
      summary: Get Available Survey Years
      description: Retrieve all years for which ARMS survey data is available.
      tags:
      - Metadata
      parameters:
      - name: api_key
        in: query
        description: API key from api.data.gov
        required: true
        schema:
          type: string
        example: DEMO_KEY
      responses:
        '200':
          description: List of available survey years
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        year:
                          type: integer
                          description: Survey year
    servers:
    - url: https://api.ers.usda.gov/data/arms
      description: USDA ERS ARMS Data API
  /state:
    get:
      operationId: getAvailableStates
      summary: Get Available States
      description: Retrieve all states and associated metadata and variables available for ARMS survey data.
      tags:
      - Metadata
      parameters:
      - name: api_key
        in: query
        description: API key from api.data.gov
        required: true
        schema:
          type: string
        example: DEMO_KEY
      responses:
        '200':
          description: List of states with available data
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        state:
                          type: string
                        stateName:
                          type: string
    servers:
    - url: https://api.ers.usda.gov/data/arms
      description: USDA ERS ARMS Data API
  /report:
    get:
      operationId: getAvailableReports
      summary: Get Available Reports
      description: Retrieve available ARMS reports with their metadata and variables. Reports represent different survey focus areas such as farm income, balance sheet, and production costs.
      tags:
      - Metadata
      parameters:
      - name: api_key
        in: query
        description: API key from api.data.gov
        required: true
        schema:
          type: string
        example: DEMO_KEY
      responses:
        '200':
          description: List of available ARMS reports
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        report:
                          type: string
                        reportTitle:
                          type: string
                        description:
                          type: string
    servers:
    - url: https://api.ers.usda.gov/data/arms
      description: USDA ERS ARMS Data API
  /variable:
    get:
      operationId: getAvailableVariables
      summary: Get Available Variables
      description: Retrieve all ARMS variables with their information and metadata, including variable codes, descriptions, and units.
      tags:
      - Metadata
      parameters:
      - name: api_key
        in: query
        description: API key from api.data.gov
        required: true
        schema:
          type: string
        example: DEMO_KEY
      - name: report
        in: query
        description: Filter variables by report name
        required: false
        schema:
          type: string
      responses:
        '200':
          description: List of ARMS variables
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        variable:
                          type: string
                        variableLabel:
                          type: string
                        description:
                          type: string
                        units:
                          type: string
    servers:
    - url: https://api.ers.usda.gov/data/arms
      description: USDA ERS ARMS Data API
  /get_param_values/:
    get:
      operationId: getParameterValues
      summary: Get Valid Parameter Values
      description: Retrieve all valid values for a specified Quick Stats parameter. Useful for building queries and understanding available data dimensions.
      tags:
      - Metadata
      parameters:
      - name: key
        in: query
        description: NASS API key
        required: true
        schema:
          type: string
      - name: param
        in: query
        description: Parameter name to retrieve values for
        required: true
        schema:
          type: string
          enum:
          - commodity_desc
          - statisticcat_desc
          - unit_desc
          - state_name
          - year
          - agg_level_desc
          - sector_desc
          - group_desc
      responses:
        '200':
          description: List of valid values for the specified parameter
          content:
            application/json:
              schema:
                type: object
                properties:
                  param:
                    type: string
                  values:
                    type: array
                    items:
                      type: string
    servers:
    - url: https://quickstats.nass.usda.gov/api
      description: USDA NASS Quick Stats API
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key
x-refined-from:
- usda-ers-arms-openapi.yml
- usda-nass-quickstats-openapi.yml