The Urban FIADB-API web application was designed to simplify the generation of population estimates and their associated sampling errors from data in the Urban Forest Inventory and Analysis database (FIADB)
urban/fullreport
The urban fullreport endpoint is the Urban estimate generation point for FIADB-API.
| geog | Urban project name(s) for which to generate estiamtes Valid options can be found in the "EVALID" column here: https://apps.fs.usda.gov/fiadb-api/urban/fullreport/parameters/geog |
|---|---|
| estnum | The urban estimate description. This is used as the numerator for ratio estimates. Valid options can be found in the "DESCRIPTION" column here: https://apps.fs.usda.gov/fiadb-api/urban/fullreport/parameters/estnum |
| grps | Grouping options for urban estimates Valid options can be found in the "LABEL_VAR" column here: https://apps.fs.usda.gov/fiadb-api/urban/fullreport/parameters/grps |
| estdenom | The urban ratio estimate denominator description. Valid options can be found in the "DESCRIPTION" column here: https://apps.fs.usda.gov/fiadb-api/urban/fullreport/parameters/estnum |
| outputFormat | Desired output format for estimate returns. Valid options are: HTML - legacy EVALIDator page/row/column cross-tabulated format - this is the default NHTML - flat table of estimate values JSON - flat formatted JSON estimate values with metadata |
| strFilter | SQL filter string with or without leading 'and'. E.g. "COND.OWNCD = 40" or "AND TREE.CCLCD in (1,2,3)" |
| numFilter | SQL filter applied to ratio estimate numerators only |
| cg1 | Custom Grouping SQL snippet 1. E.g. case when coalesce(cnd.owngrpcd, -1) in (10,20,30) then '`0001 Government' when coalesce(cnd.owngrpcd, -1) = 40 then '`0004 Private' else '`0006 Other' end |
| cg2 | Custom Grouping SQL snippet 2. E.g. case when coalesce(cnd.owngrpcd, -1) in (10,20,30) then '`0001 Government' when coalesce(cnd.owngrpcd, -1) = 40 then '`0004 Private' else '`0006 Other' end |
/urban/fullreport/parameters/<fullreport parameter name>
Adding a fullreport parameter name to the end of this endpoint will bring up a dictionary containing valid values and context for each classed parameter used in the urban fullreport endpoint
E.g. https://apps.fs.usda.gov/fiadb-api/fullreport/parameters/geog
urban/fullreport use examples
import requests
import pandas as pd
# this function will accept a FIADB-API fullreport URL and return dataframes for the estimates as well as subtotals, and totals where available.
def fiadb_api_POST(parameterDictionary):
# make request
resp = requests.post(r"https://apps.fs.usda.gov/fiadb-api/urban/fullreport",data=parameterDictionary)
# parse response to json
data = resp.json()
# create output dictionary and populate it with estimate data frames
outDict = {}
# append estimates
outDict['estimates'] = pd.DataFrame(data['estimates'])
# append subtotals and totals if present
if 'subtotals' in data.keys():
subT = {}
for i in data['subtotals'].keys():
subT[i] = pd.DataFrame(data['subtotals'][i])
outDict['subtotals'] = subT
outDict['totals'] = pd.DataFrame(data['totals'])
# append metadata
outDict['metadata'] = data['metadata']
return outDict
# example of usage
requestParameters = {'estnum':'Area of tree cover, in acres','geog':'Baltimore2021Curr', 'grps':'FIA land use', 'outputFormat':'NJSON'}
getData = fiadb_api_POST(parameterDictionary=requestParameters)
# estimate data frame
print('Estimates:\n',getData['estimates'],'\n')
# totals data frame
print('Totals:\n',getData['totals'])
# Urban evalidator API
library(httr)
library(jsonlite)
library(dplyr)
library(rlist)
geog <- jsonlite::fromJSON("https://apps.fs.usda.gov/fiadb-api/urban/fullreport/parameters/geog?outputFormat=JSON")
estnum<-jsonlite::fromJSON("https://apps.fs.usda.gov/fiadb-api/urban/fullreport/parameters/estnum?outputFormat=JSON")
grps<-jsonlite::fromJSON("https://apps.fs.usda.gov/fiadb-api/urban/fullreport/parameters/grps?outputFormat=JSON")
fiadb_api_POST <- function(argList){
# make request
resp <- POST(url="https://apps.fs.usda.gov/fiadb-api/urban/fullreport", body=argList, encode="form")
# parse response from JSON to R list
respObj <- content(resp, "parsed", encoding = "ISO-8859-1")
# create empty output list
outputList <- list()
# add estimates data frame to output list
outputList[['estimates']] <- as.data.frame(do.call(rbind,respObj$estimates))
# if estimate includes totals and subtotals, add those data frames to output list
if ('subtotals' %in% names(respObj)){
subtotals <- list()
# one subtotal data frame for each grouping variable
for (i in names(respObj$subtotals)){
subtotals[[i]] <- as.data.frame(do.call(rbind,respObj$subtotals[[i]]))}
outputList[['subtotals']] <- subtotals
# totals data frame
outputList[['totals']] <- as.data.frame(do.call(rbind,respObj$totals))
}
# add estiamte metadata
outputList[['metadata']] <- respObj$metadata
return(outputList)
}
# view options
geog[,1] # first column of geog
estnum[,1] # first column of estnum
grps[,1] # first column of estnum
# example of usage
# create a list of parameter values
argList = list(geog= 'Baltimore2021Curr',
estnum= estnum[12,1], # "Compensatory value, in dollars"
grps= grps[24,1], # "Mtree Diameter (5-inch classes)"
outputFormat='JSON')
# submit list to POST request function
postData = fiadb_api_POST(argList)
# estimate data
postData$estimates
# estimate data as a dataframe
est <- as.data.frame(lapply(postData$estimates, unlist))
# totals data frame
postData$totals
# View estimate metadata elements
names(postData[['metadata']])
# View SQL used for estimate
postData$metadata$sql