Skip to contents

Use EJScreen API to get stats on one or more circular buffers

Source: R/ejscreenapi.R
ejscreenapi.Rd

Get a data.table of EJScreen report results for one or multiple circular buffers.

Usage

ejscreenapi(
  lon,
  lat,
  radius = 3,
  unit = "miles",
  wkid = 4326,
  fips = NULL,
  shapefile = NULL,
  namestr = "",
  report_every_n = 1000,
  save_when_report = FALSE,
  format_report_or_json = "pjson",
  on_server_so_dont_save_files = FALSE,
  ipurl = "ejscreen.epa.gov",
  updateProgress = NULL,
  drop_redundant_indicators = TRUE,
  nicenames = FALSE,
  verbose = TRUE,
  getstatefromplacename = TRUE
)

Arguments

lon

Longitude numeric vector

lat

Latitude numeric vector

radius

radius of circular buffer (uses a default if none specified)

unit

"miles" (default) or "kilometers"

wkid

optional spatial reference code, if default is not what is needed

fips

if used instead of lon,lat it should be a character FIPS code vector (counties, tracts, or blockgroups)

shapefile

not implemented

namestr

optional text

report_every_n

Should it report ETA snd possibly save interim file after every n points

save_when_report

optional, write .rdata file to working directory with results so far, after ever n points, to have most results even if it crashes

format_report_or_json

default is pjson but could modify to allow it to be report to get just a pdf URL but that also can be gotten via url_ejscreen_report()

on_server_so_dont_save_files

FALSE by default, but TRUE prevents saving any progress or crash-related files

ipurl

which URL or IP to try

updateProgress

Used to create progress bar in Shiny app

drop_redundant_indicators

Set to FALSE if you do not want to exclude from results the indicators that appear twice just under 2 different names, like RAW_D_LIFEEXP and RAW_HI_LIFEEXPPCT which are identical.

nicenames

Set it to TRUE if you want to have it rename headers as long friendly plain English not R variable names but note downstream functions mostly expect rname format that uses ejscreenapi1() and ejscreenRESTbroker() and ejscreenRESTbroker2table()

verbose

whether to print to console / viewer / plot

getstatefromplacename

set to FALSE if you need the exact output of API and TRUE if you want to try to extract ST abbrev and statename from the placename field, which is more likely to be correct than the stateAbbr and stateName fields in the API output.

Details

Specify a radius and vector of latitude longitude points, and get for a buffer the population weighted mean value of each raw indicator like percent low-income, and total population count, and percentiles for those raw indicator scores, all from EJScreen, as in an EJScreen standard report.

The functions ejscreenapi_plus() and ejscreenit() are higher-level functions that provide renamed variables in their outputs. Column names returned by ejscreenapi() are those provided by the EJScreen API, e.g., RAW_D_INCOME, not the renamed variables like pctlowinc etc. or Percent Low Income

ejscreenRESTbroker() is the lowest level function here for access to the API.

ejscreenRESTbroker2table() converts that to a table.

ejscreenRESTbroker2table(ejscreenRESTbroker()) returns the same 1-row data.frame as ejscreenapi1() except the latter drops the percent signs and makes those values numeric, converting text like 45% to the number 45.

This also drops redundant columns where the same numbers had been returned from API using the normal name and a synonym name, as with TOTALPOP and "totalPop"

To compare API variable names and renamed versions:

x <- ejscreenapi(-100, 40, 1)

cbind(names(x), fixnames(names(x)))

Note this and related functions could be recoded using httr2 and some best practices, as described here: https://httr.r-lib.org/articles/api-packages.html.

This relies on ejscreenapi1() to request URL of pdf report on each site via the API, and does some error checking, but like ejscreenapi1() it does a GET request via API and then parses the JSON results from the GET request, cleans it up, adds URLs as links, compiles it as a data.table, enables a progress bar, etc.

Note that this API is fairly slow, so it is fine for 10 sites, but not large numbers. It varies, but can run about 1k to 10k sites per hour, for circular buffers of 1 or 3 mile radius. It sometimes fails to obtain results, which may be caused by unreliable results from the API rather than the code requesting results via the API.

See https://web.archive.org/web/20250118193121/https://www.epa.gov/ejscreen/ejscreen-api

See also

ejscreenit() ejscreenapi_plus() ejscreenapi()

Examples

 
 if (FALSE) { # \dontrun{
 # Specify size of buffer circle and pick random points as example data
 myradius <- 1
 pts2 <- data.frame(lon = c(-111.9040233, -73.7917865), lat = c(33.5604162, 41.0613821))
 pts5 <- testpoints_5
 
 out <- ejscreenapi(lon = pts2$lon, lat = pts2$lat, radius = myradius)
 head(t(out))
 outnice <- ejscreenapi(lon = pts2$lon, lat = pts2$lat, radius = myradius, nicenames = TRUE)
 head(t(outnice), 24)
 } # }