USDA NASS Quick Stats API — Statistics

naftiko: 1.0.0-alpha2
info:
  label: USDA NASS Quick Stats API — Statistics
  description: 'USDA NASS Quick Stats API — Statistics. 2 operations. Lead operation: Get Agricultural Statistics. Self-contained
    Naftiko capability covering one United States Department Of Agriculture business surface.'
  tags:
  - United States Department Of Agriculture
  - Statistics
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    UNITED_STATES_DEPARTMENT_OF_AGRICULTURE_API_KEY: UNITED_STATES_DEPARTMENT_OF_AGRICULTURE_API_KEY
capability:
  consumes:
  - type: http
    namespace: usda-nass-quickstats-statistics
    baseUri: https://quickstats.nass.usda.gov/api
    description: USDA NASS Quick Stats API — Statistics business capability. Self-contained, no shared references.
    resources:
    - name: api_GET
      path: /api_GET/
      operations:
      - name: getagriculturalstatistics
        method: GET
        description: Get Agricultural Statistics
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: key
          in: query
          type: string
          description: NASS API key from quickstats.nass.usda.gov
          required: true
        - name: format
          in: query
          type: string
          description: Response format
        - name: commodity_desc
          in: query
          type: string
          description: Commodity description (e.g. CORN, WHEAT, CATTLE)
        - name: statisticcat_desc
          in: query
          type: string
          description: Statistics category (e.g. AREA HARVESTED, PRODUCTION, PRICE RECEIVED)
        - name: year
          in: query
          type: string
          description: Four digit year or range using __GE or __LE operators
        - name: state_name
          in: query
          type: string
          description: Full state name
        - name: agg_level_desc
          in: query
          type: string
          description: Geographic aggregation level
        - name: freq_desc
          in: query
          type: string
          description: Frequency period descriptor
        - name: reference_period_desc
          in: query
          type: string
          description: Reference period (e.g. YEAR, JAN, FEB, MARKETING YEAR)
        - name: unit_desc
          in: query
          type: string
          description: Unit of measure (e.g. ACRES, BU, HEAD, $)
        - name: sector_desc
          in: query
          type: string
          description: Economic sector (CROPS, ANIMALS & PRODUCTS, ECONOMICS, etc.)
        - name: group_desc
          in: query
          type: string
          description: Commodity group within sector
    - name: get_counts
      path: /get_counts/
      operations:
      - name: getrecordcount
        method: GET
        description: Get Record Count
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: key
          in: query
          type: string
          description: NASS API key
          required: true
        - name: commodity_desc
          in: query
          type: string
        - name: year
          in: query
          type: string
        - name: state_name
          in: query
          type: string
        - name: agg_level_desc
          in: query
          type: string
    authentication:
      type: apikey
      key: key
      value: '{{env.UNITED_STATES_DEPARTMENT_OF_AGRICULTURE_API_KEY}}'
      placement: query
  exposes:
  - type: rest
    namespace: usda-nass-quickstats-statistics-rest
    port: 8080
    description: REST adapter for USDA NASS Quick Stats API — Statistics. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/api-get
      name: api-get
      description: REST surface for api_GET.
      operations:
      - method: GET
        name: getagriculturalstatistics
        description: Get Agricultural Statistics
        call: usda-nass-quickstats-statistics.getagriculturalstatistics
        with:
          key: rest.key
          format: rest.format
          commodity_desc: rest.commodity_desc
          statisticcat_desc: rest.statisticcat_desc
          year: rest.year
          state_name: rest.state_name
          agg_level_desc: rest.agg_level_desc
          freq_desc: rest.freq_desc
          reference_period_desc: rest.reference_period_desc
          unit_desc: rest.unit_desc
          sector_desc: rest.sector_desc
          group_desc: rest.group_desc
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/get-counts
      name: get-counts
      description: REST surface for get_counts.
      operations:
      - method: GET
        name: getrecordcount
        description: Get Record Count
        call: usda-nass-quickstats-statistics.getrecordcount
        with:
          key: rest.key
          commodity_desc: rest.commodity_desc
          year: rest.year
          state_name: rest.state_name
          agg_level_desc: rest.agg_level_desc
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: usda-nass-quickstats-statistics-mcp
    port: 9090
    transport: http
    description: MCP adapter for USDA NASS Quick Stats API — Statistics. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: get-agricultural-statistics
      description: Get Agricultural Statistics
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: usda-nass-quickstats-statistics.getagriculturalstatistics
      with:
        key: tools.key
        format: tools.format
        commodity_desc: tools.commodity_desc
        statisticcat_desc: tools.statisticcat_desc
        year: tools.year
        state_name: tools.state_name
        agg_level_desc: tools.agg_level_desc
        freq_desc: tools.freq_desc
        reference_period_desc: tools.reference_period_desc
        unit_desc: tools.unit_desc
        sector_desc: tools.sector_desc
        group_desc: tools.group_desc
      outputParameters:
      - type: object
        mapping: $.
    - name: get-record-count
      description: Get Record Count
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: usda-nass-quickstats-statistics.getrecordcount
      with:
        key: tools.key
        commodity_desc: tools.commodity_desc
        year: tools.year
        state_name: tools.state_name
        agg_level_desc: tools.agg_level_desc
      outputParameters:
      - type: object
        mapping: $.