openapi: 3.0.3
info:
  title: USDA ERS ARMS Data Statistics API
  description: The USDA Economic Research Service (ERS) Agricultural Resource Management Survey (ARMS) Data API provides access to data on farm finances, production practices, and resource use for U.S. farms. Supports attribute-based querying of farm income, balance sheet, costs, and production data by year, state, and report type. An API key from api.data.gov is required.
  version: 1.0.0
  contact:
    name: USDA Economic Research Service
    url: https://www.ers.usda.gov/developer/
  license:
    name: Public Domain
    url: https://www.usa.gov/government-works
servers:
- url: https://api.ers.usda.gov/data/arms
  description: USDA ERS ARMS Data API
tags:
- name: Statistics
  description: Agricultural statistics query and retrieval
paths:
  /api_GET/:
    get:
      operationId: getAgriculturalStatistics
      summary: Get Agricultural Statistics
      description: Query NASS agricultural statistics data using WHAT (commodity, category), WHERE (state, county, watershed), and WHEN (year, period) parameters. Returns a maximum of 50,000 records per request. Supports JSON, CSV, and XML response formats.
      tags:
      - Statistics
      parameters:
      - name: key
        in: query
        description: NASS API key from quickstats.nass.usda.gov
        required: true
        schema:
          type: string
      - name: format
        in: query
        description: Response format
        required: false
        schema:
          type: string
          enum:
          - JSON
          - CSV
          - XML
          default: JSON
      - name: commodity_desc
        in: query
        description: Commodity description (e.g. CORN, WHEAT, CATTLE)
        required: false
        schema:
          type: string
        example: CORN
      - name: statisticcat_desc
        in: query
        description: Statistics category (e.g. AREA HARVESTED, PRODUCTION, PRICE RECEIVED)
        required: false
        schema:
          type: string
        example: PRODUCTION
      - name: year
        in: query
        description: Four digit year or range using __GE or __LE operators
        required: false
        schema:
          type: string
        example: '2023'
      - name: state_name
        in: query
        description: Full state name
        required: false
        schema:
          type: string
        example: IOWA
      - name: agg_level_desc
        in: query
        description: Geographic aggregation level
        required: false
        schema:
          type: string
          enum:
          - NATIONAL
          - STATE
          - AGRICULTURAL DISTRICT
          - COUNTY
          - REGION: MULTI-STATE
          - REGION: SUB-STATE
          - WATERSHED
          - ZIP CODE
      - name: freq_desc
        in: query
        description: Frequency period descriptor
        required: false
        schema:
          type: string
          enum:
          - ANNUAL
          - SEASON
          - MONTHLY
          - WEEKLY
          - POINT IN TIME
      - name: reference_period_desc
        in: query
        description: Reference period (e.g. YEAR, JAN, FEB, MARKETING YEAR)
        required: false
        schema:
          type: string
      - name: unit_desc
        in: query
        description: Unit of measure (e.g. ACRES, BU, HEAD, $)
        required: false
        schema:
          type: string
      - name: sector_desc
        in: query
        description: Economic sector (CROPS, ANIMALS & PRODUCTS, ECONOMICS, etc.)
        required: false
        schema:
          type: string
      - name: group_desc
        in: query
        description: Commodity group within sector
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Agricultural statistics data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuickStatsResponse'
        '400':
          description: Request resulted in more than 50,000 records or invalid parameters
        '403':
          description: Invalid or expired API key
  /get_counts/:
    get:
      operationId: getRecordCount
      summary: Get Record Count
      description: Get the number of records matching a set of query parameters without retrieving the full dataset. Useful for verifying queries stay under the 50,000 record limit.
      tags:
      - Statistics
      parameters:
      - name: key
        in: query
        description: NASS API key
        required: true
        schema:
          type: string
      - name: commodity_desc
        in: query
        required: false
        schema:
          type: string
      - name: year
        in: query
        required: false
        schema:
          type: string
      - name: state_name
        in: query
        required: false
        schema:
          type: string
      - name: agg_level_desc
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Record count for the query
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Number of matching records
components:
  schemas:
    StatRecord:
      type: object
      description: An individual agricultural statistics record
      properties:
        source_desc:
          type: string
          description: Data source (SURVEY or CENSUS)
        sector_desc:
          type: string
          description: Economic sector
        group_desc:
          type: string
          description: Commodity group
        commodity_desc:
          type: string
          description: Commodity name
        class_desc:
          type: string
          description: Commodity class or variety
        prodn_practice_desc:
          type: string
          description: Production practice
        util_practice_desc:
          type: string
          description: Utilization practice
        statisticcat_desc:
          type: string
          description: Statistics category
        unit_desc:
          type: string
          description: Unit of measurement
        short_desc:
          type: string
          description: Abbreviated item description
        domain_desc:
          type: string
          description: Domain (TOTAL, AREA OPERATED, etc.)
        domaincat_desc:
          type: string
          description: Domain category
        agg_level_desc:
          type: string
          description: Geographic aggregation level
        state_ansi:
          type: string
          description: ANSI state code
        state_fips_code:
          type: string
          description: FIPS state code
        state_alpha:
          type: string
          description: Two-letter state abbreviation
        state_name:
          type: string
          description: Full state name
        asd_code:
          type: string
          description: Agricultural Statistics District code
        asd_desc:
          type: string
          description: Agricultural Statistics District description
        county_ansi:
          type: string
          description: ANSI county code
        county_code:
          type: string
          description: County FIPS code
        county_name:
          type: string
          description: County name
        region_desc:
          type: string
          description: Multi-state or sub-state region
        zip_5:
          type: string
          description: ZIP code
        watershed_code:
          type: string
          description: Watershed code
        watershed_desc:
          type: string
          description: Watershed description
        congr_district_code:
          type: string
          description: Congressional district code
        country_code:
          type: string
          description: Country code
        country_name:
          type: string
          description: Country name
        location_desc:
          type: string
          description: Location description
        year:
          type: integer
          description: Survey or census year
        freq_desc:
          type: string
          description: Data frequency
        begin_code:
          type: string
          description: Begin period code
        end_code:
          type: string
          description: End period code
        reference_period_desc:
          type: string
          description: Reference time period
        week_ending:
          type: string
          description: Week ending date (weekly data)
        load_time:
          type: string
          description: Timestamp when data was loaded
        Value:
          type: string
          description: Statistical value (may include commas and formatting)
        CV (%):
          type: string
          description: Coefficient of variation
    QuickStatsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/StatRecord'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key