openapi: 3.0.3
info:
  title: USDA ERS ARMS Data Metadata 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: 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
  /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
  /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
  /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
  /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
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key