├── README.md └── _config.yml /README.md: -------------------------------------------------------------------------------- 1 | ## 1. Introduction 2 | 3 | USDA’s Economic Research Services (ERS) is making data from USDA’s Agriculture Resource Management Survey (ARMS) available through an Application Programming Interface (API) to better serve customers. The data in the API are available in JSON format and provide attribute-based querying. The data are also available in bulk files. 4 | 5 | This page provides a brief explanation of the API to get you started. For user convenience, we provide demos using R: open source statistical programming language. 6 | 7 | A list of variables, by report, is provided in section 3. An exhaustive list of all variables and detailed descriptions is found in the file AllVariables.csv. 8 | 9 | ## 2. Getting Started with the ARMS-Data-API 10 | 11 | You may use the ARMS Data API to develop a service to search, display, analyze, retrieve, view, and otherwise "get" information from ARMS data. 12 | 13 | ### 2.1 14 | Users of the ARMS data API are required to sign up for an API key via api.data.gov, a free API management service for Federal agencies. A valid email address is required to obtain a key. Once users have completed the signup requirements, the API key will be automatically sent to the user-provided email address. API keys provide a means to notify users of changes in the APIs. 15 | 16 | **Note:** A key is not required to use the bulk download facility. 17 | 18 | ### 2.2 Using the API 19 | The API support GraphQL and REST API methods: 20 | 21 | * Rest API 22 | 23 | Rest API endpoint: https://api.ers.usda.gov/data/ 24 | 25 | **REST Methods** 26 | 27 | The REST API supports POST and GET methods for calling data, except where noted. 28 | 29 | Each endpoint also supports the OPTIONS method that returns the endpoint schema and details on input fields and requirements, such as format, whether the field allows 30 | 31 | **/arms/state** 32 | 33 | This API resource gets all States and the metadata and variables available for each of the States. 34 | 35 | _Input fields:_ not needed 36 | 37 | _Method_: supports GET only 38 | 39 | ``` 40 | GET https://api.ers.usda.gov/data/arms/state?api_key=YOUR_API_KEY 41 | ``` 42 | 43 | **/arms/year** 44 | 45 | This API resource gets all available years for which data are available. 46 | 47 | _Input fields:_ not needed 48 | 49 | _Method:_ supports GET only 50 | 51 | ``` 52 | GET https://api.ers.usda.gov/data/arms/year?api_key=YOUR_API_KEY 53 | ``` 54 | 55 | **/arms/surveydata** 56 | 57 | _Input fields:_ "Year" is a required field; at least one of the two input fields ("report" or "variable") is also required 58 | 59 | _Method:_ supports GET and POST 60 | 61 | _OPTION:_ returns the schema for the survey data REST resource 62 | 63 | ``` 64 | POST https://api.ers.usda.gov/data/arms/surveydata?api_key=YOUR_API_KEY 65 | 66 | { 67 | "year": [2011, 2012, 2013, 2014, 2015, 2016] 68 | "state": "all" 69 | "variable": "igcfi" 70 | "category": "NASS Regions" 71 | "category2": "Collapsed Farm Typology" 72 | } 73 | ``` 74 | 75 | The above retrieves "Gross Farm Income" for years 2011 through 2016 for "All States" and broken by Category = NASS regions and Category2 = Collapsed Farm Typology. 76 | 77 | ```GET https://api.ers.usda.gov/data/arms/surveydata?api_key=YOUR_API_KEY?year=2015,2016&state=all&report=income+statement&farmtype=operator+households&category=collapsed+farm+typology&category_value=commercial``` 78 | This GET request returns income statements for years 2015 and 2016 of commercial farms across all States. 79 | 80 | **Note:** Multiple values for fields that allow multiple values are separated by "commas" (,), and names of fields exceeding more than one word are separated by a "plus" (+). Different query parameters such as year, states, report, etc. are separated by an "ampersand" (&). 81 | 82 | **/arms/category** 83 | 84 | This API resource lists categories and subcategories within each category. It also provides relevant metadata and variables available for each of the categories and subcategories. 85 | 86 | _Input fields:_ not required but can be passed on; see below. 87 | 88 | _Method:_ supports GET and POST 89 | 90 | This resource can be used in two ways: 91 | 92 | 1. When used without any input variables, ALL categories and subcategories are returned. 93 | 94 | `POST https://api.ers.usda.gov/data/arms/category?api_key=YOUR_API_KEY` 95 | 96 | `GET https://api.ers.usda.gov/data/arms/category?api_key=YOUR_API_KEY` 97 | 98 | 2. When used with a specific category name, all details and subcategories within that category are returned 99 | 100 | `POST https://api.ers.usda.gov/data/arms/category?api_key=YOUR_API_KEY` 101 | 102 | ```{ 103 | "name": "Collapsed Farm Typology" 104 | } 105 | ``` 106 | 107 | `GET https://api.ers.usda.gov/data/arms/category?id=age,ftypll` 108 | 109 | This query returns Category-related information for "Operator age" (id=age) and "Farm Typology" (id = ftypll) 110 | 111 | **/arms/report** 112 | 113 | This API resource gets available reports with the relevant metadata and variables available for each report. This resource can be used in two ways: 114 | 115 | 1. Retrieve a list of ALL reports 116 | 117 | `POST https://api.ers.usda.gov/data/arms/report?api_key=YOUR_API_KEY` 118 | 119 | `GET https://api.ers.usda.gov/data/arms/report?api_key=YOUR_API_KEY` 120 | 121 | 2. Retrieve metadata and variables for a specific report based on name, ID, or keyword. 122 | 123 | `POST https://api.ers.usda.gov/data/arms/report?api_key=YOUR_API_KEY` 124 | 125 | ```{ 126 | "name": "balance sheet" 127 | } 128 | ``` 129 | 130 | **/arms/variable** 131 | 132 | This API resource gets variables with the relevant information and metadata for each of the variables used in ARMS. This resource can be used in two ways: 133 | 134 | 1. List ALL variables. 135 | 136 | ```POST https://api.ers.usda.gov/data/arms/variable?api_key=YOUR_API_KEY``` 137 | 138 | ```GET https://api.ers.usda.gov/data/arms/variable?api_key=YOUR_API_KEY``` 139 | 140 | 2. Search "variable" by ID, report, name, and keywords. All input fields are optional, and one can use all or none of them to get the desired data. 141 | 142 | ```POST https://api.ers.usda.gov/data/arms/variable?api_key=YOUR_API_KEY 143 | { 144 | "report": "Business Balance Sheet" 145 | "name": "Liabilities current debt" 146 | } 147 | ``` 148 | 149 | **/arms/farmtype** 150 | 151 | One can use this REST resource to get all Farm Types or search by keyword, name, or ID. 152 | 153 | _Input fields:_ optional 154 | 155 | _Method:_ supports GET and POST 156 | 157 | `POST https://api.ers.usda.gov/data/arms/farmtype?api_key=YOUR_API_KEY` 158 | 159 | `{ 160 | "name": "operator households" 161 | }` 162 | 163 | `GET https://api.ers.usda.gov/data/arms/farmtype?api_key=YOUR_API_KEY` 164 | `GET https://api.ers.usda.gov/data/arms/farmtype?api_key=YOUR_API_KEY&name=operator+households` 165 | 166 | * GraphQL 167 | 168 | GraphQL is a modern method to easily interact with an API. The GraphQL endpoint for ARMS data is https://api.ers.usda.gov/data/arms/graphql. 169 | 170 | * GraphQL methods 171 | 172 | GraphQL is for advanced users. If you are not familiar with GraphQL, use our REST API. A GraphQL client, such as ChromeiQL, is needed to interact with the ARMS API. More information on GraphQL is available. 173 | 174 | ## 3. Reports 175 | 176 | ARMS reports are a collection of financial data points about U.S.-based farms that can be sorted and viewed in a variety of ways, including national level, State level, farmer type, and farmer age. 177 | 178 | The ARMS team has created some commonly used tailored reports from the ARMS dataset. Currently, the following tailored reports are available on the WebTool and through the API: 179 | 180 | * Farm Business Balance Sheet 181 | * Farm Business Income Statement 182 | * Farm Business Financial Ratios 183 | * Structural Characteristics 184 | * Farm Business Debt Repayment Capacity 185 | * Government Payments 186 | * Operator Household Income 187 | * Operator Household Balance Sheet 188 | 189 | ## 4. Variables 190 | Each report contains a different set of variables. A list of all variables sorted by report and with detailed descriptions and short IDs may be found in the file AllVariables.csv. 191 | 192 | ## 5. Available Categories 193 | Categories are meta tags that provide context for the data. The available categories are listed below with their short IDs inside the parenthesis. Values for each category and their definitions may be found in the file AllVariables.csv. 194 | 195 | * Residence farms 196 | * Intermediate farms 197 | * Commercial farms 198 | 199 | Economic Class (sal) 200 | 201 | * $1,000,000 or more 202 | * $500,000 to $999,999 203 | * $250,000 to $499,999 204 | * $100,000 to $249,999 205 | * less than $100,000 206 | 207 | Farm Typology (ftyppl) 208 | 209 | * Retirement farms (2012 to present) 210 | * Off-farm occupation farms (2012 to present) 211 | * Farming occupation/lower sales farms (2012 to present) 212 | * Farming occupation/moderate-sales farms (2012 to present) 213 | * Midsize farms (2012 to present) 214 | * Large farms (2012 to present) 215 | * Very large farms (2012 to present) 216 | * Nonfamily farms (2012 to present) 217 | * Retirement farms (1996 through 2011) 218 | * Residential/lifestyle farms (1996 through 2011) 219 | * Farming occupation/lower sales farms (1996 through 2011) 220 | * Farming occupation/moderate-sales farms (1996 through 2011) 221 | * Large farms (1996 through 2011) 222 | * Very large farms (1996 through 2011) 223 | * Nonfamily farms (1996 through 2011) 224 | 225 | Operator age (age) 226 | 227 | * 34 years or younger 228 | * 35 to 44 years old 229 | * 45 to 54 years old 230 | * 55 to 64 years old 231 | * 65 years or older 232 | 233 | Farm Resource Region (reg) 234 | 235 | * Heartland 236 | * Northern Crescent 237 | * Northern Great Plains 238 | * Prairie Gateway 239 | * Eastern Uplands 240 | * Southern Seaboard 241 | * Fruitful Rim 242 | * Basin and Range 243 | * Mississippi Portal 244 | 245 | NASS region (n5reg) 246 | 247 | * Atlantic region 248 | * South region 249 | * Midwest region 250 | * Plains region 251 | * West region 252 | 253 | Production Specialty (spec) 254 | 255 | * Tobacco, cotton, peanuts 256 | * Other field crops 257 | * Cattle 258 | * Dairy 259 | * Hogs, poultry, other 260 | * Vegetables 261 | * Nursery and greenhouse 262 | * All cash grains 263 | * Specialty crops 264 | * All other livestock 265 | 266 | ## 6. Updates and Revisions 267 | 268 | **December 18, 2020** 269 | 270 | A database update was released on December 18, 2020, containing new data for 2019 and updates and revisions to historical data across 1996-2018. See full description on the ARMS data product here). 271 | 272 | This update includes the release of new farm and household finances data for 2019 and includes changes to improve internal consistency in data-handling methods. 273 | 274 | * Previously posted estimates of Adjusted Gross Income (AGI) for 1996-2018 were updated to reflect a change in methods for how limitations to deduct retirement contributions as well other deductions are modeled across time. The new limitations result in an increase in estimated AGI of $4,400 at the national level (5.3 percent) compared to the previous method. 275 | 276 | * Estimated value of production for farm operations in 2018 was revised downward by $3.83 billion (1.1 percent) due to corrections in processing the underlying survey data, especially potato production, and due to a restatement of a marketing contract record. Value of production is directly reported in the structural characteristics tailored report. Also, because value of production is used to classify the commodity specialization of operations restating value of production resulted in changes to the number of farms for several of the commodity specialization categories. The largest increase in operations within a single category was in operations classified as primarily specialty crop (fruit, vegetable, and nut) operations, raising the total of specialty crop operations by 1029, or 0.7 percent, to 148,931 operations, with smaller increases in the number of farms classified as "other field crops" and "general cash grains" operations, and also resulted in a corresponding decrease in the number of farms otherwise classified as "wheat," "corn," "soybeans," or "tobacco, cotton, or peanuts" operations. 277 | 278 | * For 2018 data, estimates for four financial ratios included in the financial indicators report are updated with new information on agricultural wage rates released in the National Agricultural Statistics Service (NASS) Farm Labor survey. The agricultural wage rate is used as an implicit hourly wage for reported operator labor hours. The implicit labor cost is used in calculating the rate of return to assets and equity, operating profit margin, and economic cost-to-output ratio. The wage rate increase reduced the return to assets and equity by 0.1 and 0.2 percentage points, to 0.4 and 0.0 percent respectively, and reduced the operating profit margin by 1.2 percentage points to 3.1 percent. It increased the economic cost-to-output ratio by 2.3 percentage points to 111.5. 279 | 280 | * For 2011 data, a procedure was implemented to impute reported government payment amounts by category for certain operations, resulting in a small (less than 0.1 percent) change in the number of operations receiving direct payments and countercyclical-type payments, as well as the average amounts of these types of payments, and the average gross cash and net cash farm income for recipients of these types of program payments. The total amount of government payments recorded in 2011 is unchanged. 281 | 282 | * The standard method for calculating land tenure status for farm operations, which classified operations as either a full ownership operation, part owner operation, or full tenant operation, was extended to data from 1997 to 2003, changing the share of full owner operations downward by 0.4 percentage points, on average, and part owner operations up an equal amount. In determining the categorical status, the standard method accounts for acres rented in by operations as well as acres rented out. 283 | 284 | **December 10, 2019** 285 | 286 | **Errata:** On December 10, 2019, the data found in Tailored Reports: Farm Structure and Finance was revised to correct an error in the calculation of average and median net farm income estimates for 2012-17. Revised net farm income estimates impact all "subject" and "filter" selections for average and median net farm income, 2012-17. Estimates of U.S. average net farm income, for example, are revised downward by -4.5 to -8.8 percent across the 6 years, lowering these estimates by $1,858 to $4,409. The error was restricted to the underlying calculation of the net farm income variable alone; no other data values were affected within the income statement. However, net farm income is a component in the calculation of a subset of financial ratios also found in the tailored reports. Thus, the reported rate of return on assets, rate of return on equity, operating profit margin, and term debt coverage ratio estimates for 2012-17 are revised as well. 287 | 288 | New data in this release include: 289 | * In the Government Payments tailored report, a revised classification of government payments from 1996 to the present into five separate program types (direct payments, countercyclical-type payments, marketing loan benefit payments, conservation payments, and other program payments). These categories are described more fully in The Evolving Distribution of Payments From Commodity, Conservation, and Federal Crop Insurance Programs(EIB-184, November 2017). The change will improve comparisons across years because the previous method for categorizing government programs referred to individual farm bill programs that did not persist across the entire time period. 290 | 291 | * In the Farm Household Income tailored report, a new variable from 1996 onward showing a household's Adjusted Gross Income (AGI). Adjusted Gross Income is calculated using formulas and specifications found in IRS Form 1040 of each corresponding tax year. AGI as reported in the table includes deductions for self-employed health insurance and self-employment taxes. Adjusted Gross Income as calculated from ARMS data is described more fully in Estimated Effects of the Tax Cuts and Jobs Act on Farms and Farm Households(ERR-252, June 2018). 292 | 293 | * Within the Farm Business Income Statement tailored report, a new variable is shown from 2012 onward for Adjusted Breeding Livestock Income. The variable is one of five variables that account for the difference between net cash farm income and net farm income. For operations with income from the sale of breeding livestock, net cash farm income includes the cash receipts from the sale of breeding livestock, while net farm income includes only the realized gain or loss from the sale of breeding livestock, calculated as cash receipts minus acquisition costs. All five variables accounting for the difference between net cash farm income and net farm income in the Farm Business income statement (nonmoney income, value of inventory change, depreciation, labor non-cash benefits, and adjusted breeding livestock income) are show in the farm business income statement beginning with this release. 294 | 295 | Additionally, this update improves data-handling methods for improved consistency across time. 296 | 297 | * ERS' standard imputation method for handling missing survey data on farm debt for 2012 to the present was extended back to 2009 data. The change in methods resulted in an increase in total debt by 7 percent, on average, across 2009-11, and also affect debt-based financial ratios including the current ratio, the working capital-to-expense ratio, the debt-to-asset ratio, and the term debt coverage ratio. 298 | 299 | * Prevailing interest rate data from Chicago Federal Reserve's AgLetter was used to replace multiple sources of interest rate data across 1996-2018. The difference in interest rates used for formula calculations averaged 65 basis points (0.65 percentage points) per year. This data is used in calculating Financial Ratios and Debt Repayment Capacity tailored reports from 1996 to 2008, and market interest rates are also used to impute debt appearing in the Farm Business Balance Sheet and the Operator Household Balance Sheet from 1996 to 2018. Debt-based financial ratios including the current ratio, the working capital-to-expense ratio, the debt-to-asset ratio, and the term debt coverage ratio are similarly impacted. 300 | 301 | * In the Structural Characteristics tailored report, the standard method for calculating the classification of farms by their land tenure categories "including a full owner, part owner, and full tenant category" was consistently applied to all farm operations across time, changing previously-reported values for 1997 and 2004-06. The standard method takes into account acres rented in by operators as well as acres rented out. From 3 to 5 percent of farms switched from their previous categories as a result of changes in 1997 and 2004-06. 302 | 303 | 304 | **August 29, 2019** 305 | 306 | A database update was released on August 27, 2019, containing revised data for 2017 and other changes (see full description on the ARMS data product here). 307 | 308 | * The “searching”, and “formatting” properties of the “info” section of the API query result have been removed in this version of the API. 309 | * Each record of the category query result contains a new category “description” property. 310 | * Each record of the report query result contains a new report “desc” property. 311 | * Each record of the farmtype query result contains a new farmtype “desc” property. 312 | * Each record of the surveydata query result contains a new “decimal_display” property, indicating the proper number of decimals to display for the value. 313 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-minimal --------------------------------------------------------------------------------