USDA NASS QuickStats API — Statistics

naftiko: 1.0.0-alpha2
info:
  label: USDA NASS QuickStats API — Statistics
  description: 'USDA NASS QuickStats API — Statistics. 2 operations. Lead operation: USDA NASS Get Statistics. Self-contained
    Naftiko capability covering one Agricultural Statistics Service business surface.'
  tags:
  - Agricultural Statistics Service
  - Statistics
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    AGRICULTURAL_STATISTICS_SERVICE_API_KEY: AGRICULTURAL_STATISTICS_SERVICE_API_KEY
capability:
  consumes:
  - type: http
    namespace: quickstats-statistics
    baseUri: https://quickstats.nass.usda.gov/api
    description: USDA NASS QuickStats API — Statistics business capability. Self-contained, no shared references.
    resources:
    - name: api_GET
      path: /api_GET
      operations:
      - name: getstatistics
        method: GET
        description: USDA NASS Get Statistics
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: key
          in: query
          type: string
          description: API key obtained by registering at the QuickStats API portal.
          required: true
        - name: commodity_desc
          in: query
          type: string
          description: Commodity description (e.g., CORN, SOYBEANS, CATTLE).
        - name: class_desc
          in: query
          type: string
          description: Commodity class description.
        - name: statisticcat_desc
          in: query
          type: string
          description: Statistical category (e.g., AREA HARVESTED, PRODUCTION, PRICE RECEIVED).
        - name: unit_desc
          in: query
          type: string
          description: Unit of measurement (e.g., ACRES, BU, HEAD).
        - name: sector_desc
          in: query
          type: string
          description: Sector or division of the agricultural economy.
        - name: group_desc
          in: query
          type: string
          description: Commodity group description (e.g., FIELD CROPS, VEGETABLES).
        - name: state_alpha
          in: query
          type: string
          description: Two-letter state abbreviation (e.g., VA, IA, TX).
        - name: state_name
          in: query
          type: string
          description: Full state name.
        - name: county_name
          in: query
          type: string
          description: County name.
        - name: agg_level_desc
          in: query
          type: string
          description: Geographic aggregation level (NATIONAL, STATE, COUNTY, ZIP CODE).
        - name: year
          in: query
          type: integer
          description: Survey year (e.g., 2023). Supports operators like year__GE=2010.
        - name: year__GE
          in: query
          type: integer
          description: Year greater than or equal to specified value.
        - name: year__LE
          in: query
          type: integer
          description: Year less than or equal to specified value.
        - name: freq_desc
          in: query
          type: string
          description: Data collection frequency (ANNUAL, MONTHLY, WEEKLY, POINT IN TIME, SEASONAL).
        - name: reference_period_desc
          in: query
          type: string
          description: Reference period description (e.g., YEAR, JAN, JUN).
        - name: format
          in: query
          type: string
          description: Response format (JSON, XML, CSV). Defaults to JSON.
        - name: callback
          in: query
          type: string
          description: JSONP callback function name for cross-origin requests.
    - name: get_counts
      path: /get_counts
      operations:
      - name: getcounts
        method: GET
        description: USDA NASS Get Record Counts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: key
          in: query
          type: string
          description: API key.
          required: true
        - name: commodity_desc
          in: query
          type: string
          description: Commodity description to count records for.
        - name: state_alpha
          in: query
          type: string
          description: State abbreviation to filter.
        - name: year__GE
          in: query
          type: integer
          description: Year filter (greater than or equal).
    authentication:
      type: apikey
      key: key
      value: '{{env.AGRICULTURAL_STATISTICS_SERVICE_API_KEY}}'
      placement: query
  exposes:
  - type: rest
    namespace: quickstats-statistics-rest
    port: 8080
    description: REST adapter for USDA NASS QuickStats 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: getstatistics
        description: USDA NASS Get Statistics
        call: quickstats-statistics.getstatistics
        with:
          key: rest.key
          commodity_desc: rest.commodity_desc
          class_desc: rest.class_desc
          statisticcat_desc: rest.statisticcat_desc
          unit_desc: rest.unit_desc
          sector_desc: rest.sector_desc
          group_desc: rest.group_desc
          state_alpha: rest.state_alpha
          state_name: rest.state_name
          county_name: rest.county_name
          agg_level_desc: rest.agg_level_desc
          year: rest.year
          year__GE: rest.year__GE
          year__LE: rest.year__LE
          freq_desc: rest.freq_desc
          reference_period_desc: rest.reference_period_desc
          format: rest.format
          callback: rest.callback
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/get-counts
      name: get-counts
      description: REST surface for get_counts.
      operations:
      - method: GET
        name: getcounts
        description: USDA NASS Get Record Counts
        call: quickstats-statistics.getcounts
        with:
          key: rest.key
          commodity_desc: rest.commodity_desc
          state_alpha: rest.state_alpha
          year__GE: rest.year__GE
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: quickstats-statistics-mcp
    port: 9090
    transport: http
    description: MCP adapter for USDA NASS QuickStats API — Statistics. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: usda-nass-get-statistics
      description: USDA NASS Get Statistics
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: quickstats-statistics.getstatistics
      with:
        key: tools.key
        commodity_desc: tools.commodity_desc
        class_desc: tools.class_desc
        statisticcat_desc: tools.statisticcat_desc
        unit_desc: tools.unit_desc
        sector_desc: tools.sector_desc
        group_desc: tools.group_desc
        state_alpha: tools.state_alpha
        state_name: tools.state_name
        county_name: tools.county_name
        agg_level_desc: tools.agg_level_desc
        year: tools.year
        year__GE: tools.year__GE
        year__LE: tools.year__LE
        freq_desc: tools.freq_desc
        reference_period_desc: tools.reference_period_desc
        format: tools.format
        callback: tools.callback
      outputParameters:
      - type: object
        mapping: $.
    - name: usda-nass-get-record-counts
      description: USDA NASS Get Record Counts
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: quickstats-statistics.getcounts
      with:
        key: tools.key
        commodity_desc: tools.commodity_desc
        state_alpha: tools.state_alpha
        year__GE: tools.year__GE
      outputParameters:
      - type: object
        mapping: $.