{"id":32158031,"url":"https://github.com/alejandromerchan/usdaquickstats.jl","last_synced_at":"2026-04-02T14:51:07.448Z","repository":{"id":61799949,"uuid":"258886674","full_name":"alejandromerchan/USDAQuickStats.jl","owner":"alejandromerchan","description":"Package to access USDA's NASS Quick Stats","archived":false,"fork":false,"pushed_at":"2022-06-21T19:15:07.000Z","size":47,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-21T12:57:04.019Z","etag":null,"topics":["database","julia","nass","usda"],"latest_commit_sha":null,"homepage":null,"language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alejandromerchan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-25T22:25:54.000Z","updated_at":"2021-10-20T03:35:04.000Z","dependencies_parsed_at":"2022-10-21T11:30:55.817Z","dependency_job_id":null,"html_url":"https://github.com/alejandromerchan/USDAQuickStats.jl","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/alejandromerchan/USDAQuickStats.jl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandromerchan%2FUSDAQuickStats.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandromerchan%2FUSDAQuickStats.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandromerchan%2FUSDAQuickStats.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandromerchan%2FUSDAQuickStats.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alejandromerchan","download_url":"https://codeload.github.com/alejandromerchan/USDAQuickStats.jl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alejandromerchan%2FUSDAQuickStats.jl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29710317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T10:34:24.778Z","status":"ssl_error","status_checked_at":"2026-02-22T10:32:23.200Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","julia","nass","usda"],"created_at":"2025-10-21T12:56:57.672Z","updated_at":"2026-02-22T11:02:44.506Z","avatar_url":"https://github.com/alejandromerchan.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"# USDAQuickStats.jl\n\n\n`USDAQuickStats.jl` provides functions to access data from the USDA National Agricultural Statistics Service (NASS) [Quick Stats database](https://quickstats.nass.usda.gov/api) API in Julia.\n\n## Installation\n\n```@julia\nadd USDAQuickStats\n```\n## Index\n\nThe package contains following functions:\n\n- `set_api_key`\n- `get_counts`\n- `get_param_values`\n- `get_nass`\n\n## Tutorial and Workflow\n### Set up an Environment Variable for the NASS API key\n\nTo start using the API, the user first needs to get a **personal API key**.\n\nThe user can request a NASS API key at [https://quickstats.nass.usda.gov/api](https://quickstats.nass.usda.gov/api).\n\nThe API key can be saved as an environment variable called \"USDA_QUICK_SURVEY_KEY\" or used during each new Julia session by setting it up using:\n\n```@julia\nusing USDAQuickStats\nset_api_key(\"YOUR_KEY\"::String)\n```\n\nreplacing `\"YOUR_KEY\"` with the private API key as a string.\n\nSaving the key into a permanent variable in your environment is dependent on the operating system.\n\n### Query the database\n\nThe API for the Quick Stats database provides three main functions:\n\n- get_nass\n- get_counts\n- get_param_values\n\n**get_nass**\n\n`get_nass(args...; format=\"json\")\n`\nThe main function is `get_nass`, which queries the main USDA Quick Stats database.\n\n`args...` is a list of the different headers from the database that can be queried. Each argument is a string with the name of the header and the value from that header in uppercase, e.g. `\"header=VALUE`. The description of the different headers (also called columns) for the database is available [here].(https://quickstats.nass.usda.gov/api)\n\nThe `format` keyword can be added to the query after a semicolon `;` and defines the format of the response. It is set to `JSON` as a default, other formats provided by the database are `CSV` and `XML`.\n\nThe function returns a HTTP.request object and the user can parse it using different packages, some examples below.\n\nIn the following example, the survey data for oranges in California (CA) for the year 2019 was queried for information about the headers \"ACRES BEARING\" and \"PRICE RECEIVED\". The format keyword isn't specified, so the request will return a JSON file. \n\nNotice that header values that have spaces in them need to be passed with the symbol `%20` replacing the space. In general, no spaces are allowed in the query.\n\n```@julia\nquery = get_nass(\"source_desc=SURVEY\",\"commodity_desc=ORANGES\",\"state_alpha=CA\", \"year=2019\",\"statisticcat_desc=AREA%20BEARING\",\"statisticcat_desc=PRICE%20RECEIVED\")\n```\noutput\n\n```@julia\nHTTP.Messages.Response:\n\"\"\"\nHTTP/1.1 200 OK\nDate: Sat, 26 Dec 2020 19:36:55 GMT\nServer: Apache/2.4.23 (Linux/SUSE)\nX-Frame-Options: SAMEORIGIN\nContent-Length: 274515\nCache-Control: max-age=86400, private\nConnection: close\nContent-Type: application/json\nStrict-Transport-Security: max-age=31536000; includeSubDomains; preload\n\n{\"data\":[{\"begin_code\":\"00\",\"prodn_practice_desc\":\"ALL PRODUCTION PRACTICES\",\"watershed_desc\":\"\",\"state_fips_code\":\"06\",\"commodity_desc\":\"ORANGES\",\"statisticcat_desc\":\"AREA BEARING\",\"Value\":\"147,000\",\"watershed_code\":\"00000000\",\"source_desc\":\"SURVEY\",\"util_practice_desc\":\"ALL UTILIZATION PRACTICES\",\"domaincat_desc\":\"NOT SPECIFIED\",\"domain_desc\":\"TOTAL\",\"state_alpha\":\"CA\",\"week_ending\":\"\",\"group_desc\":\"FRUIT \u0026 TREE NUTS\",\"reference_period_desc\":\"YEAR\",\"CV (%)\":\"\",\"year\":2019,\"short_desc\":\"ORANGES - ACRES BEARING\",\"country_code\":\"9000\",\"load_time\":\"2019-08-28 15:09:57\",\"country_name\":\"UNITED STATES\",\"unit_desc\":\"ACRES\",\"county_code\":\"\",\"end_code\":\"00\",\"sector_desc\":\"CROPS\",\"state_name\":\"CALIFORNIA\",\"zip_5\":\"\",\"class_desc\":\"ALL CLASSES\",\"county_ansi\":\"\",\"asd_code\":\"\",\"location_desc\":\"CALIFORNIA\",\"congr_district_code\":\"\",\"county_name\":\"\",\"state_ansi\":\"06\",\"region_desc\":\"\",\"asd_desc\":\"\",\"freq_desc\":\"ANNUAL\",\"agg_level_desc\":\"STATE\"},{\"reference_period_desc\":\"MARKETING YEAR\",\"CV (%)\":\"\",\"yea\n⋮\n274515-byte body\n\"\"\"\n```\n\nThis query object can be post-processed in different ways, depending on the format. JSON is the default format and the object can be displayed using the packages JSON3.jl, JSONTables.jl and DataFrames.jl.\n\n```@julia\nusing JSON3\nusing JSONTables\nusing DataFrames\n\njobject = JSON3.read(query.body)\njtable = jsontable(jobject.data)\ndf = DataFrame(jtable)\n```\n\nThe query can also be returned and processed as a CSV file.\n\n```@julia\nusing CSV\nusing DataFrames\n\nquery = get_nass(\"source_desc=SURVEY\",\"commodity_desc=ORANGES\",\"state_alpha=CA\", \"year=2019\",\"statisticcat_desc=AREA%20BEARING\",\"statisticcat_desc=PRICE%20RECEIVED\"; format=\"csv\")\n\n# Display as DataFrame\nCSV.read(query.body, DataFrame)\n\n# Or save it to disk\nCSV.write(\"query.csv\", CSV.File(query.body))\n```\n\nThe query can also return an XML file.\n\n**get_param_values**\n\n`get_param_values(arg)` is a helper query that allow user to check the values of a field `arg` from the database. This is useful when constructing different query strings, as it allows the user to determine which values are available on each field.\n\n```@julia\ndb_values = get_param_values(\"sector_desc\")\n```\n\noutput\n\n```@julia\nHTTP.Messages.Response:\n\"\"\"\nHTTP/1.1 200 OK\nDate: Sat, 26 Dec 2020 20:40:29 GMT\nServer: Apache/2.4.23 (Linux/SUSE)\nX-Frame-Options: SAMEORIGIN\nContent-Length: 89\nCache-Control: max-age=86400, private\nConnection: close\nContent-Type: application/json\nStrict-Transport-Security: max-age=31536000; includeSubDomains; preload\n\n{\"sector_desc\":[\"ANIMALS \u0026 PRODUCTS\",\"CROPS\",\"DEMOGRAPHICS\",\"ECONOMICS\",\"ENVIRONMENTAL\"]}\"\"\"\n```\nThe query object can be post processed using the JSON3 package to obtain a more readable output if needed.\n```@julia\nusing JSON3\n\nJSON3.read(db_values.body)\n```\n\n**get_counts**\n\n`get_counts(args...)` is a helper query that allows user to check the number of records a query using the fields in `args...` will produce before performing the query. This is important because the USDA Quick Stats API has a limit of 50,000 records per query. Any query requesting a number of records larger than this limit will fail.\n\nAs in `get_nass`, `args...` is a list of the different headers from the database that can be queried. Each argument is a string with the name of the header and the value from that header in uppercase, e.g. `\"header=VALUE`. The description of the different headers (also called columns) for the database is available [here].(https://quickstats.nass.usda.gov/api)\n\nIn the following example, the number of records for survey data for oranges in California (CA) for the year 2019 with information about the headers \"ACRES BEARING\" and \"PRICE RECEIVED\" was queried. \n\nNotice that header values that have spaces in them need to be passed with the symbol `%20` replacing the space. In general, no spaces are allowed in the query.\n\n```@julia\ncount = get_counts(\"source_desc=SURVEY\",\"commodity_desc=ORANGES\",\"state_alpha=CA\", \"year=2019\",\"statisticcat_desc=AREA%20BEARING\",\"statisticcat_desc=PRICE%20RECEIVED\")\n```\n\noutput\n\n```@julia\nHTTP.Messages.Response:\n\"\"\"\nHTTP/1.1 200 OK\nDate: Sat, 26 Dec 2020 20:47:55 GMT\nServer: Apache/2.4.23 (Linux/SUSE)\nX-Frame-Options: SAMEORIGIN\nContent-Length: 13\nCache-Control: max-age=86400, private\nConnection: close\nContent-Type: application/json\nStrict-Transport-Security: max-age=31536000; includeSubDomains; preload\n\n{\"count\":276}\"\"\"\n```\n\nSame as before, the object can be processed with the JSON3 package to get a more readable output.\n\nA very large query would be for example:\n\n```@julia\nget_counts(\"source_desc=SURVEY\", \"year=2019\")\n```\n\noutput\n\n```@julia\nHTTP.Messages.Response:\n\"\"\"\nHTTP/1.1 200 OK\nDate: Sat, 26 Dec 2020 20:49:14 GMT\nServer: Apache/2.4.23 (Linux/SUSE)\nX-Frame-Options: SAMEORIGIN\nContent-Length: 16\nCache-Control: max-age=86400, private\nConnection: close\nContent-Type: application/json\nStrict-Transport-Security: max-age=31536000; includeSubDomains; preload\n\n{\"count\":448878}\"\"\"\n```\nThis query would fail if ran directly using the `get_nass` function, because it exceeds the limit of 50000 rows.\n\nI would like to thank @markushhh, because I heavily used his [FredApi.jl](https://github.com/markushhh/FredApi.jl) for inspiration. And sometimes blatant plagiarism.\n\n## Each comment, suggestion or pull request is welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falejandromerchan%2Fusdaquickstats.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falejandromerchan%2Fusdaquickstats.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falejandromerchan%2Fusdaquickstats.jl/lists"}