Skip to contents

Get URL(s) of HTML summary reports for use with EJAM-API

Source: R/url_ejamapi.R
url_ejamapi.Rd

Get URL(s) of HTML summary reports for use with EJAM-API

Usage

url_ejamapi(
  sitepoints = NULL,
  lat = NULL,
  lon = NULL,
  radius = 3,
  fips = NULL,
  shapefile = NULL,
  dTolerance = 100,
  linktext = "Report",
  as_html = FALSE,
  ifna = NULL,
  baseurl = NULL,
  sitenumber = "each",
  version = NULL,
  ...,
  shape = NULL,
  shp = NULL
)

Arguments

sitepoints

see ejamit()

lat, lon

can be provided as vectors of coordinates instead of providing sitepoints table

radius

analysis radius in miles; see ejamit(). Default is 3 miles for point (lat/lon/sitepoints) analysis, but 0 (no buffer) when fips or shapefile is specified.

fips

see ejamit()

shapefile

see ejamit(), but each polygon is encoded as geojson string which might get too long for encoding in a URL for the API using GET

dTolerance

number of meters tolerance to use in sf::st_simplify() to simplify polygons to fit as url-encoded text geojson. Only used when a shapefile/polygon is provided; ignored for point (lat/lon) or fips analysis.

linktext

used as text for hyperlinks, if supplied and as_html=TRUE

as_html

if FALSE (default) returns plain character URL(s); if TRUE returns HTML hyperlinks (via url_linkify()) suitable for use in a DT::datatable() or other HTML context

ifna

URL shown for missing, NA, NULL, bad input values. Default NULL (and an explicitly passed NULL) resolves to the EJAM API base URL from DESCRIPTION (ejam_api_url), via url_package() with type="api".

baseurl

do not change unless endpoint actually changed. Default NULL (and an explicitly passed NULL) resolves to the DESCRIPTION ejam_api_url followed by "/report?". See ejamapi() for a better way to handle choice of endpoint.

sitenumber

controls how many URLs are returned and which site(s) each covers:

  • "each" (or -1) – the default – returns a vector of URLs, one per site (one single-site report per site). Unlike ejam2report()/ejam2map(), which never return a vector, the url_* helpers can; that vector-per-site output is the main reason this parameter exists.

  • "overall" (or 0, NULL, or "") – returns a single URL requesting one aggregate multisite report combining all sites (sent to the API as sitenumber=0; assumes >1 site was provided).

  • N (a number > 0) – returns a single URL for just the Nth site found in the inputs (e.g. the 3rd point, fips, or polygon).

Single-site auto-override: when the inputs resolve to exactly one site (one row of sitepoints, one fips code, or one polygon), sitenumber is coerced to 1 regardless of what was requested, so a lone place yields a single-site report URL.

version

optional EJAM version tag (e.g. "3.2024.0") sent to the API as version= so the API can serve the matching data vintage. Default NULL resolves to the installed package Version (from DESCRIPTION).

...

a named list of other query parameters passed to the API, to allow for expansion of allowed parameters

shape, shp

aliases (synonyms) for shapefile

Value

vector of character string URLs – see details on sitenumber parameter

Details

  • Relies on the EJAM REST API, whose source code is at https://github.com/Public-Environmental-Data-Partners/EJAM-API (the API base URL itself comes from url_package("api"); see the ejam_api_url field in DESCRIPTION).

  • To construct a "deep link" that launches the live EJAM app (not the API) pre-loaded with sites, see url_ejamapp(), which uses the same query vocabulary (lat, lon, fips, shape, radius, handoff).

  • Accepts a subset of ejamit()'s input-parameter names (sitepoints, lat, lon, radius, fips, shapefile); it does not accept every ejamit()/ejam2report() option (see the note below on unsupported options).

  • The API honors the sitenumber parameter passed through to ejam2report(): sitenumber = 1 requests a single-site report (the API's per-request default when none is supplied), and sitenumber = 0 (or "overall") produces an aggregate multisite report. (Note url_ejamapi()'s own default is sitenumber = "each" – see the parameter docs below.) The API leaves the report title to ejam2report(), which uses "EJSCREEN Community Report" for a single site and "EJSCREEN Multisite Summary" for the aggregate. Many or large polygons can exceed URL length for this GET-based path; the API also provides a POST /report endpoint for those. The API does not yet accept every ejam2report() option (e.g. logo_path, thresholds & threshnames, radius_donut_lower_edge).

See also

ejamapi() url_ejamapp() url_package()

Examples


 pts = data.frame(lat=37.64122, lon=-122.41065)
 pts2 = data.frame(lat = c(37.64122, 43.92249), lon = c(-122.41065, -72.663705))
 pts10 = testpoints_10
 pts_fname = system.file("testdata/latlon/testpoints_10.xlsx", package="EJAM")

  # vector of 1-site report URLs
 x = url_ejamapi(pts_fname)
 x = url_ejamapi(sitepoints = pts2)
 x_bysite = url_ejamapi(pts10, radius = 3.1, sitenumber = "each")

 ## 1 summary report URL - may not be implemented yet
 # x_overall = url_ejamapi(pts10, radius = 3.1, sitenumber = "overall")

 # FIPS Census units
 y = url_ejamapi(fips = c("050014801001", "050014802001"))
 ## blockgroups may not be implemented yet
 # y = url_ejamapi(fips = testinput_fips_mix)

 # Polygons
 shp = testinput_shapes_2[2, c("geometry", "FIPS", "NAME")]
 z = url_ejamapi(shapefile = shp)

 # HTML hyperlinks (e.g. for a DT::datatable cell) instead of plain URLs
 x_links = url_ejamapi(pts2, as_html = TRUE, linktext = "Report")

 if (FALSE) { # \dontrun{
 browseURL(paste0(url_package("api"), "/report?lat=33&lon=-112&buffer=4"))  # API base from DESCRIPTION

 browseURL(x[1])
 browseURL(y[1])
 browseURL(z[1])
} # }