nasspython 1.0.0

Wrapper for the NASS Quickstats database

nasspython

A wrapper for the NASS Quickstats API for Python, modeled off of the R package documented here: https://github.com/rdinter/usdarnass

You can find the database here: https://quickstats.nass.usda.gov/

---

Functions provided:

nass_count

Description

Checks the number of observations that will be returned in a data request. All queries to the QuickStats are limited to 50,000 observations. This is a helpful function in determining how to structurea data request to fit within the 50,000 limit.

Arguments

• Inital argument is your API key for NASS Quickstats
• source_desc: "Program" - Source of data ("CENSUS" or "SURVEY"). Census program in-cludes the Census of Ag as well as follow up projects. Survey program includesnational, state, and county surveys.
• sector_desc: "Sector" - Five high level, broad categories useful to narrow down choices.("ANIMALS & PRODUCTS", "CROPS", "DEMOGRAPHICS", "ECONOMICS",or "ENVIRONMENTAL")
• group_desc: "Group" - Subsets within sector (e.g., under sector_desc = "CROPS", the groupsare "FIELD CROPS", "FRUIT & TREE NUTS", "HORTICULTURE", and "VEG-ETABLES").
• commodity_desc: "Commodity" - The primary subject of interest (e.g., "CORN", "CATTLE","LABOR", "TRACTORS", "OPERATORS").
• short_desc: "Data Item" - A concatenation of six columns: commodity_desc, class_desc,prodn_practice_desc, util_practice_desc, statisticcat_desc, and unit_desc.
• domain_desc: "Domain" - Generally another characteristic of operations that produce a partic-ular commodity (e.g., "ECONOMIC CLASS", "AREA OPERATED", "NAICSCLASSIFICATION", "SALES"). For chemical usage data, the domain de-scribes the type of chemical applied to the commodity. The domain_desc ="TOTAL" will have no further breakouts; i.e., the data value pertains completelyto the short_desc.
• domaincat_desc: "Domain Category" - Categories or partitions within a domain (e.g., under do-main_desc = "SALES", domain categories include $1,000 TO $9,999, $10,000TO $19,999, etc).
• agg_level_desc: "Geographic Level" - Aggregation level or geographic granularity of the data.("AGRICULTURAL DISTRICT", "COUNTY", "INTERNATIONAL", "NA-TIONAL", "REGION : MULTI-STATE", "REGION : SUB-STATE", "STATE","WATERSHED", or "ZIP CODE")
• statisticcat_desc: "Category" - The aspect of a commodity being measured (e.g., "AREA HAR-VESTED", "PRICE RECEIVED", "INVENTORY", "SALES").
• state_name: "State" - State full name.
• asd_desc: "Ag District" - Ag statistics district name.
• county_name: "County" - County name.
• region_desc: "Region" - NASS defined geographic entities not readily defined by other stan-dard geographic levels. A region can be a less than a state (SUB-STATE) or agroup of states (MULTI-STATE), and may be specific to a commodity.
• zip_5: "Zip Code" - US Postal Service 5-digit zip code.
• watershed_desc: "Watershed" - Name assigned to the HUC.
• year: "Year" - The numeric year of the data and can be either a character or numericvector.
• freq_desc: "Period Type" - Length of time covered ("ANNUAL", "SEASON", "MONTHLY","WEEKLY", "POINT IN TIME"). "MONTHLY" often covers more than onemonth. "POINT IN TIME" is as of a particular day.
• reference_period_desc: "Period" - The specific time frame, within a freq_desc.

Return Value

Number of observations.

Examples

Return count of all observations in NASS:
nass_count(<your api key>)

Find the number of observations for Wake County in North Carolina:
nass_count(<your api key>, state_name = "NORTH CAROLINA", county_name = "WAKE")

---

nass_data

Description

Sends query to Quick Stats API from given parameter values. Data request is limited to 50,000 records per the API. Use nass_count to determine number of records in query.

Arguments

• Inital argument is your API key for NASS Quickstats
• source_desc: "Program" - Source of data ("CENSUS" or "SURVEY"). Census program in-cludes the Census of Ag as well as follow up projects. Survey program includesnational, state, and county surveys.
• sector_desc: "Sector" - Five high level, broad categories useful to narrow down choices.("ANIMALS & PRODUCTS", "CROPS", "DEMOGRAPHICS", "ECONOMICS",or "ENVIRONMENTAL")
• group_desc: "Group" - Subsets within sector (e.g., under sector_desc = "CROPS", the groupsare "FIELD CROPS", "FRUIT & TREE NUTS", "HORTICULTURE", and "VEG-ETABLES").
• commodity_desc: "Commodity" - The primary subject of interest (e.g., "CORN", "CATTLE","LABOR", "TRACTORS", "OPERATORS").
• short_desc: "Data Item" - A concatenation of six columns: commodity_desc, class_desc,prodn_practice_desc, util_practice_desc, statisticcat_desc, and unit_desc.
• domain_desc: "Domain" - Generally another characteristic of operations that produce a partic-ular commodity (e.g., "ECONOMIC CLASS", "AREA OPERATED", "NAICSCLASSIFICATION", "SALES"). For chemical usage data, the domain de-scribes the type of chemical applied to the commodity. The domain_desc ="TOTAL" will have no further breakouts; i.e., the data value pertains completelyto the short_desc.
• domaincat_desc: "Domain Category" - Categories or partitions within a domain (e.g., under do-main_desc = "SALES", domain categories include $1,000 TO $9,999, $10,000TO $19,999, etc).
• agg_level_desc: "Geographic Level" - Aggregation level or geographic granularity of the data.("AGRICULTURAL DISTRICT", "COUNTY", "INTERNATIONAL", "NA-TIONAL", "REGION : MULTI-STATE", "REGION : SUB-STATE", "STATE","WATERSHED", or "ZIP CODE")
• statisticcat_desc: "Category" - The aspect of a commodity being measured (e.g., "AREA HAR-VESTED", "PRICE RECEIVED", "INVENTORY", "SALES").
• state_name: "State" - State full name.
• asd_desc: "Ag District" - Ag statistics district name.
• county_name: "County" - County name.
• region_desc: "Region" - NASS defined geographic entities not readily defined by other stan-dard geographic levels. A region can be a less than a state (SUB-STATE) or agroup of states (MULTI-STATE), and may be specific to a commodity.
• zip_5: "Zip Code" - US Postal Service 5-digit zip code.
• watershed_desc: "Watershed" - Name assigned to the HUC.
• year: "Year" - The numeric year of the data and can be either a character or numericvector.
• freq_desc: "Period Type" - Length of time covered ("ANNUAL", "SEASON", "MONTHLY","WEEKLY", "POINT IN TIME"). "MONTHLY" often covers more than onemonth. "POINT IN TIME" is as of a particular day.
• reference_period_desc: "Period" - The specific time frame, within a freq_desc.
• format: Output format from API call. Defaults to CSV as it is typically the smallestsized call. Other options are JSON and XML but these are not recommended.
• numeric_vals: Optional to convert the year, value, and coefficient of variation (CV %) to numerics as opposed to defaulted character values. Default is to FALSE as some values have a suppression code. Converting to numeric will result in suppressed values to be NA.

Return Value

JSON object of query results

Examples

Get state values in 2012 for all of the values of agricultural land:
nass_data(<your API key>, agg_level_desc = "STATE", year = "2012",commodity_desc = "AG LAND", domain_desc = "VALUE")

Get county level values in 2012 for the specific data item:
nass_data(<your API key>, year = 2012, agg_level_desc = "COUNTY",short_desc = "AG LAND, INCL BUILDINGS - ASSET VALUE, MEASURED IN $")

---

nass_param

Description

All possible values of a parameter for a given query. Helps to break down possible results from nass_data.

Arguments

• Inital argument is your API key for NASS Quickstats
• param: A valid parameter value. Available names are: source_desc, sector_desc, group_desc,commodity_desc, short_desc, domain_desc, domaincat_desc, agg_level_desc,statisticcat_desc, state_name, asd_desc, county_name, region_desc, zip_5, wa-tershed_desc, year, freq_desc, and reference_period_desc.
• source_desc: "Program" - Source of data ("CENSUS" or "SURVEY"). Census program in-cludes the Census of Ag as well as follow up projects. Survey program includesnational, state, and county surveys.
• sector_desc: "Sector" - Five high level, broad categories useful to narrow down choices.("ANIMALS & PRODUCTS", "CROPS", "DEMOGRAPHICS", "ECONOMICS",or "ENVIRONMENTAL")
• group_desc: "Group" - Subsets within sector (e.g., under sector_desc = "CROPS", the groupsare "FIELD CROPS", "FRUIT & TREE NUTS", "HORTICULTURE", and "VEG-ETABLES").
• commodity_desc: "Commodity" - The primary subject of interest (e.g., "CORN", "CATTLE","LABOR", "TRACTORS", "OPERATORS").
• short_desc: "Data Item" - A concatenation of six columns: commodity_desc, class_desc,prodn_practice_desc, util_practice_desc, statisticcat_desc, and unit_desc.
• domain_desc: "Domain" - Generally another characteristic of operations that produce a partic-ular commodity (e.g., "ECONOMIC CLASS", "AREA OPERATED", "NAICSCLASSIFICATION", "SALES"). For chemical usage data, the domain de-scribes the type of chemical applied to the commodity. The domain_desc ="TOTAL" will have no further breakouts; i.e., the data value pertains completelyto the short_desc.
• domaincat_desc: "Domain Category" - Categories or partitions within a domain (e.g., under do-main_desc = "SALES", domain categories include $1,000 TO $9,999, $10,000TO $19,999, etc).
• agg_level_desc: "Geographic Level" - Aggregation level or geographic granularity of the data.("AGRICULTURAL DISTRICT", "COUNTY", "INTERNATIONAL", "NA-TIONAL", "REGION : MULTI-STATE", "REGION : SUB-STATE", "STATE","WATERSHED", or "ZIP CODE")
• statisticcat_desc: "Category" - The aspect of a commodity being measured (e.g., "AREA HAR-VESTED", "PRICE RECEIVED", "INVENTORY", "SALES").
• state_name: "State" - State full name.
• asd_desc: "Ag District" - Ag statistics district name.
• county_name: "County" - County name.
• region_desc: "Region" - NASS defined geographic entities not readily defined by other stan-dard geographic levels. A region can be a less than a state (SUB-STATE) or agroup of states (MULTI-STATE), and may be specific to a commodity.
• zip_5: "Zip Code" - US Postal Service 5-digit zip code.
• watershed_desc: "Watershed" - Name assigned to the HUC.
• year: "Year" - The numeric year of the data and can be either a character or numericvector.
• freq_desc: "Period Type" - Length of time covered ("ANNUAL", "SEASON", "MONTHLY","WEEKLY", "POINT IN TIME"). "MONTHLY" often covers more than onemonth. "POINT IN TIME" is as of a particular day.
• reference_period_desc: "Period" - The specific time frame, within a freq_desc.

Return Value

JSON object of all possible parameter values

Examples

Return the program sources for data:
nass_param(<your API key>, "source_desc")

Return the group categories available in the CROPS sector:
nass_param(<your API key>, param = "group_desc", sector_desc = "CROPS")

---