openapi: 3.0.3 info: title: USDA NASS QuickStats API description: >- The QuickStats API provides direct programmatic access to the statistical information contained in the NASS Quick Stats database, covering official published aggregate estimates related to U.S. agricultural production from NASS surveys and the Census of Agriculture. Supports filtering by commodity, location (state, county, zip), and time with comparison operators. Returns data in JSON, XML, or CSV format. An API key is required. Maximum 50,000 records per request. version: v1 contact: url: https://www.nass.usda.gov/ email: nass@usda.gov x-generated-from: documentation servers: - url: https://quickstats.nass.usda.gov/api description: USDA NASS QuickStats API tags: - name: Statistics description: Agricultural statistics data retrieval and filtering - name: Parameters description: Parameter value discovery for query building paths: /api_GET: get: operationId: getStatistics summary: USDA NASS Get Statistics description: >- Retrieves agricultural statistics data records from the Quick Stats database. Supports filtering by commodity, location, time period, and statistical category using comparison operators. Returns up to 50,000 records per request. Response formats include JSON (default), XML, and CSV. tags: - Statistics parameters: - name: key in: query description: API key obtained by registering at the QuickStats API portal. required: true schema: type: string example: YOUR_API_KEY - name: commodity_desc in: query description: Commodity description (e.g., CORN, SOYBEANS, CATTLE). required: false schema: type: string example: CORN - name: class_desc in: query description: Commodity class description. required: false schema: type: string example: ALL CLASSES - name: statisticcat_desc in: query description: Statistical category (e.g., AREA HARVESTED, PRODUCTION, PRICE RECEIVED). required: false schema: type: string example: AREA HARVESTED - name: unit_desc in: query description: Unit of measurement (e.g., ACRES, BU, HEAD). required: false schema: type: string example: ACRES - name: sector_desc in: query description: Sector or division of the agricultural economy. required: false schema: type: string example: CROPS - name: group_desc in: query description: Commodity group description (e.g., FIELD CROPS, VEGETABLES). required: false schema: type: string example: FIELD CROPS - name: state_alpha in: query description: Two-letter state abbreviation (e.g., VA, IA, TX). required: false schema: type: string example: VA - name: state_name in: query description: Full state name. required: false schema: type: string example: VIRGINIA - name: county_name in: query description: County name. required: false schema: type: string example: FAIRFAX - name: agg_level_desc in: query description: Geographic aggregation level (NATIONAL, STATE, COUNTY, ZIP CODE). required: false schema: type: string enum: - NATIONAL - STATE - COUNTY - ZIP CODE - REGION example: STATE - name: year in: query description: Survey year (e.g., 2023). Supports operators like year__GE=2010. required: false schema: type: integer example: 2023 - name: year__GE in: query description: Year greater than or equal to specified value. required: false schema: type: integer example: 2010 - name: year__LE in: query description: Year less than or equal to specified value. required: false schema: type: integer example: 2023 - name: freq_desc in: query description: Data collection frequency (ANNUAL, MONTHLY, WEEKLY, POINT IN TIME, SEASONAL). required: false schema: type: string enum: - ANNUAL - MONTHLY - WEEKLY - POINT IN TIME - SEASONAL example: ANNUAL - name: reference_period_desc in: query description: Reference period description (e.g., YEAR, JAN, JUN). required: false schema: type: string example: YEAR - name: format in: query description: Response format (JSON, XML, CSV). Defaults to JSON. required: false schema: type: string enum: - JSON - XML - CSV example: JSON - name: callback in: query description: JSONP callback function name for cross-origin requests. required: false schema: type: string example: myCallback responses: '200': description: Agricultural statistics data records matching the query. content: application/json: schema: $ref: '#/components/schemas/StatisticsResponse' examples: GetStatistics200Example: summary: Default getStatistics 200 response x-microcks-default: true value: data: - source_desc: SURVEY sector_desc: CROPS group_desc: FIELD CROPS commodity_desc: CORN class_desc: ALL CLASSES prodn_practice_desc: ALL PRODUCTION PRACTICES util_practice_desc: ALL UTILIZATION PRACTICES statisticcat_desc: AREA HARVESTED unit_desc: ACRES short_desc: CORN - ACRES HARVESTED domain_desc: TOTAL domaincat_desc: NOT SPECIFIED agg_level_desc: STATE state_ansi: '51' state_fips_code: '51' state_alpha: VA state_name: VIRGINIA asd_code: '00' asd_desc: STATE TOTAL county_ansi: '' county_code: '' county_name: '' zip_5: '' region_desc: '' watershed_code: '' watershed_desc: '' congr_district_code: '' country_code: '9000' country_name: UNITED STATES location_desc: VIRGINIA year: 2023 freq_desc: ANNUAL begin_code: '00' end_code: '00' reference_period_desc: YEAR week_ending: '' load_time: '2024-01-15 09:30:00' value: '400,000' CV_pct: '' '400': description: Bad request. Too many records or invalid parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized. Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK /get_param_values: get: operationId: getParamValues summary: USDA NASS Get Parameter Values description: >- Returns all possible values for a specified QuickStats parameter, helping users discover valid values for building queries. Useful for finding valid commodity names, state codes, statistical categories, and other parameter values. tags: - Parameters parameters: - name: key in: query description: API key. required: true schema: type: string example: YOUR_API_KEY - name: param in: query description: >- The parameter name for which to return all valid values (e.g., commodity_desc, state_alpha, statisticcat_desc). required: true schema: type: string example: commodity_desc responses: '200': description: All valid values for the specified parameter. content: application/json: schema: $ref: '#/components/schemas/ParamValuesResponse' examples: GetParamValues200Example: summary: Default getParamValues 200 response x-microcks-default: true value: param_values: - CORN - SOYBEANS - WHEAT - CATTLE - HOGS '401': description: Unauthorized. Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK /get_counts: get: operationId: getCounts summary: USDA NASS Get Record Counts description: >- Returns the total count of records that would be returned by a given query without fetching the actual data. Useful for validating queries before making full data requests, particularly to ensure results stay within the 50,000 record limit. tags: - Statistics parameters: - name: key in: query description: API key. required: true schema: type: string example: YOUR_API_KEY - name: commodity_desc in: query description: Commodity description to count records for. required: false schema: type: string example: CORN - name: state_alpha in: query description: State abbreviation to filter. required: false schema: type: string example: VA - name: year__GE in: query description: Year filter (greater than or equal). required: false schema: type: integer example: 2010 responses: '200': description: Count of records matching the query. content: application/json: schema: $ref: '#/components/schemas/CountResponse' examples: GetCounts200Example: summary: Default getCounts 200 response x-microcks-default: true value: count: 1250 '401': description: Unauthorized. Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK components: securitySchemes: ApiKeyQuery: type: apiKey in: query name: key description: >- API key obtained by registering at https://quickstats.nass.usda.gov/api and agreeing to NASS Terms of Service. schemas: StatisticsRecord: type: object title: Statistics Record description: A single agricultural statistics data record from the QuickStats database. properties: source_desc: type: string description: Data source type (SURVEY or CENSUS). example: SURVEY sector_desc: type: string description: High-level sector of the agricultural economy. example: CROPS group_desc: type: string description: Commodity group within the sector. example: FIELD CROPS commodity_desc: type: string description: Name of the agricultural commodity. example: CORN class_desc: type: string description: Commodity class or subtype. example: ALL CLASSES statisticcat_desc: type: string description: Statistical measurement category. example: AREA HARVESTED unit_desc: type: string description: Unit of measurement for the value. example: ACRES short_desc: type: string description: Short description combining commodity and statistic. example: CORN - ACRES HARVESTED domain_desc: type: string description: Domain category (TOTAL, CHEMICAL, IRRIGATION, etc.). example: TOTAL agg_level_desc: type: string description: Geographic aggregation level. example: STATE state_alpha: type: string description: Two-letter state abbreviation. example: VA state_name: type: string description: Full state name. example: VIRGINIA county_name: type: string description: County name (if county-level data). example: FAIRFAX year: type: integer description: Survey or census year. example: 2023 freq_desc: type: string description: Data collection frequency. example: ANNUAL reference_period_desc: type: string description: Reference time period (YEAR, JAN, JUN, etc.). example: YEAR value: type: string description: Statistical value (may include formatting like commas; use as string). example: '400,000' CV_pct: type: string description: Coefficient of variation percentage (data reliability indicator). example: '' StatisticsResponse: type: object title: Statistics Response description: Response from the QuickStats api_GET endpoint. properties: data: type: array items: $ref: '#/components/schemas/StatisticsRecord' description: Array of statistics records matching the query. ParamValuesResponse: type: object title: Parameter Values Response description: Response containing all valid values for a parameter. properties: param_values: type: array items: type: string description: List of valid values for the requested parameter. example: - CORN - SOYBEANS - WHEAT CountResponse: type: object title: Count Response description: Response containing the record count for a query. properties: count: type: integer description: Total number of records matching the query parameters. example: 1250 ErrorResponse: type: object title: Error Response description: Error response from the QuickStats API. properties: error: type: string description: Error type or description. example: too many results message: type: string description: Human-readable error message. example: The request would return more than 50,000 records. Please narrow your query. security: - ApiKeyQuery: []