Chapter 2 API Requests
2.1 Constructing Cal-Adapt API Requests
In order to fetch data thru the Cal-Adapt API, you have to first construct an API Request object. The basic elements of an API Request include:
- location(s)
- dataset(s)
- date range
- temporal aggregation period
- spatial aggregation function
In practice, you build an API request object by mixing and matching different functions that provide difference pieces of the request, joining them by pipes. Example:
Anatomy of an API Request Object
library(caladaptr)
sacramento_cap <-
ca_loc_pt(coords = c(-119.0, 35.4)) %>% ## location
ca_cvar("tasmin") %>% ## climate variable (part of the dataset specification)
ca_gcm(gcms[1:4]) %>% ## climate models (part of the dataset specification)
ca_scenario("rcp45") %>% ## emissions scenario (part of the dataset specification)
ca_period("year") %>% ## temporal aggregation
ca_years(start = 2070, end = 2099) ## date rangeNotes:
- the order of the functions that comprise an API Request object doesn’t matter
- typically you save the API request as an object so you can feed it into other functions
- nearly all of the functions in
caladaptrstart withca_
- an API Request object doesn’t contain any climate data, that’s a separate step
2.2 Checking an API Request
There are a few ways you can check an API Request object, prior to using it to fetch data from the server.
- print it to the console
- plot it (will show a map of the location(s))
- feed it into
ca_preflight()
These methods will be shown below.
2.3 Locations of Interest
The location(s) of interest in an API Request can be specified by:
- a data frame with columns for longitude-latitude coordinates
- a point or polygon simple feature data frame from the sf package
- the name of a preset area of interest
An API Request object can contain multiple locations, but they must all be the same type. You can’t mix and match different types of locations in the same API request.
The coverage area of Cal-Adapt’s LOCA downscaled data is:
library(sf, quietly = TRUE)
loca_bnd_sf <- system.file("extdata", "loca_area.geojson", package = "caladaptr") %>%
sf::st_read(quiet = TRUE)
library(leaflet, quietly = TRUE)
leaflet(loca_bnd_sf) %>% addTiles() %>% addPolygons()2.3.1 Longitude-Latitude Coordinates
You can specify the location of an API request using longitude-latitude coordinates. Use the ca_loc_pt() function:
mysites_df <- data.frame(id = 1:3,
lon = c(-123.2, -122.4, -123.5),
lat = c(42.1, 41.8, 40.5))
mysites_df
mysites_cap <- ca_loc_pt(coords = mysites_df[,2:3], id = mysites_df[,1]) %>%
ca_gcm(gcms[1:4]) %>%
ca_scenario("rcp45") %>%
ca_cvar(c("tasmax")) %>%
ca_period("year") %>%
ca_years(start = 2040, end = 2070)
mysites_cap## id lon lat
## 1 1 -123.2 42.1
## 2 2 -122.4 41.8
## 3 3 -123.5 40.5
## Cal-Adapt API Request
## Location(s):
## x: -123.2, -122.4, -123.5
## y: 42.1, 41.8, 40.5
## Variable(s): tasmax
## Temporal aggregration period(s): year
## GCM(s): HadGEM2-ES, CNRM-CM5, CanESM2, MIROC5
## Scenario(s): rcp45
## Dates: 2040-01-01 to 2070-12-31
## Notes:
- the data frame you pass for
coordsshould contain two and only two columns: longitude and latitude. The column names are not important, but they must be in that order. - the
idargument lets you pass a vector or column of location id that will be returned with the climate data so you can join them back to the locations - an API request should not contain duplicate locations
2.3.2 Simple Feature Data Frame
You can query your own geometry using a simple feature data frame (sf package) with ca_loc_sf(). Points and polygons are supported.
pinnacles_bnd <- st_read("https://github.com/UCANR-IGIS/caladaptr-res/raw/main/geoms/pinnacles_bnd.geojson")## Reading layer `pinnacles_bnd' from data source
## `https://github.com/UCANR-IGIS/caladaptr-res/raw/main/geoms/pinnacles_bnd.geojson'
## using driver `GeoJSON'
## Simple feature collection with 1 feature and 5 fields
## Geometry type: MULTIPOLYGON
## Dimension: XY
## Bounding box: xmin: -121.2455 ymin: 36.4084 xmax: -121.1012 ymax: 36.56416
## Geodetic CRS: WGS 84pincl_cap <- ca_loc_sf(loc = pinnacles_bnd) %>%
ca_gcm(gcms[1:4]) %>%
ca_scenario("rcp45") %>%
ca_cvar(c("tasmax")) %>%
ca_period("year") %>%
ca_years(start = 2040, end = 2070) %>%
ca_options(spatial_ag = "mean")
pincl_cap %>% plot(locagrid = TRUE, static = TRUE)
pincl_cap %>% ca_preflight()## General issues
## - none found
## Issues for querying values
## - none found
## Issues for downloading rasters
## - none foundNotes
- the sf object needs have a CRS (which will be transformed to geographic coordinates if needed)
- Multipart points are not supported (use
st_castto convert them to simple points) - to join the climate data back to the sf object, use the argument
idfldto pass a column from the sf object with unique values
2.3.3 Preset Area of Interest
The Cal-Adapt API has its own polygon areas-of-interest (also known as boundary layers). Using one of the preset areas-of-interest simplifies things, because you don’t have to prepare and submit your own polygon object. The preset areas-of-interest include:
aoipreset_types## [1] "censustracts" "counties" "cdistricts"
## [4] "ccc4aregions" "climregions" "hydrounits"
## [7] "irwm" "electricutilities" "wecc-load-area"
## [10] "evtlocations" "place"To get data for one or more features from one of these preset AOIs, use
glenn_cnty_cap <- ca_loc_aoipreset(type = "counties", idfld = "fips", idval = "06021") %>%
ca_cvar("pr") %>%
ca_scenario("rcp45") %>%
ca_period("day") %>%
ca_gcm(gcms[1:4]) %>%
ca_years(start = 2036, end = 2065) %>%
ca_options(spatial_ag = "mean")
glenn_cnty_cap %>% ca_preflight()## General issues
## - none found
## Issues for querying values
## - none found
## Issues for downloading rasters
## - none foundplot(glenn_cnty_cap, locagrid = TRUE)
The only hard part about using preset areas-of-interest is finding the id value(s) of the feature(s) you’re interested in. For census tracts and counties, this might be a FIPS code. For watersheds, it’s a HUC10 code. For other preset AOIs, it may a name or something else. To find out which fields you can use to specify a feature, use the built-in constant aoipreset_idflds. For example, if we wanted to see which fields we can use to specify a congressional district, we could run:
aoipreset_idflds$cdistricts## [1] "geoid" "id"
Next, to find the id value of features of interest, look at the attribute table of the layer. You can import any preset area-of-interest layer into R as a sf object using ca_aoipreset_geom(). For example, suppose we want to get historical precipitation for the north eastern most part of the Sierra Nevada range as defined by the 4th Climate Change Assessment. We can find the id for this polygon with:
aoipreset_idflds$ccc4aregions## [1] "name" "id"ccc4aregions_sf <- ca_aoipreset_geom("ccc4aregions", quiet = TRUE)
glimpse(ccc4aregions_sf)## Rows: 12
## Columns: 3
## $ name <chr> "Central Coast", "Inland South", "Los Angeles", "North Coast", "S~
## $ id <int> 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27
## $ geom <MULTIPOLYGON [m]> MULTIPOLYGON (((-13551745 4..., MULTIPOLYGON (((-12924787 3..., M~ccc4aregions_sf$name## [1] "Central Coast" "Inland South"
## [3] "Los Angeles" "North Coast"
## [5] "Sacramento Valley" "San Diego"
## [7] "San Francisco Bay Area" "San Joaquin Valley"
## [9] "Sierra Nevada Mountains N Sierra" "Sierra Nevada Mountains NE Sierra"
## [11] "Sierra Nevada Mountains S Sierra" "Sierra Nevada Mountains SE Sierra"
With that info in hand, we can set up our API Object as follows:
srnv_ne_cap <- ca_loc_aoipreset(type = "ccc4aregions",
idfld = "name",
idval = "Sierra Nevada Mountains NE Sierra") %>%
ca_livneh(TRUE) %>%
ca_cvar(c("tasmax")) %>%
ca_period("year") %>%
ca_years(start = 1980, end = 2010) %>%
ca_options(spatial_ag = "mean")
srnv_ne_cap %>% ca_preflight()## General issues
## - none found
## Issues for querying values
## - none found
## Issues for downloading rasters
## - none foundsrnv_ne_cap %>% plot(locagrid = TRUE, static = FALSE)