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,
  fileextension = "auto",
  ...,
  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 field Config/EJAM/url_api, via url_package() with type="api".

baseurl

do not change unless endpoint actually changed. Default NULL (and an explicitly passed NULL) resolves to url_package("api"), a URL stored in DESCRIPTION as Config/EJAM/url_api, 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. Each URL sends only its own site to the API but also carries sitenumber=N (that site's row number in the inputs) so the API labels the report header "Site N" instead of calling every per-site report Site 1 (Public-Environmental-Data-Partners/EJAM#348).

  • "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). The URL carries sitenumber=N when N > 1 (as for "each" above; omitted when N is 1 since Site 1 is the API's default label).

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 (with no sitenumber parameter in it).

version

optional EJAM version tag (e.g. "3.2024.0") sent to the API as version= so the API can be asked to serve the matching data vintage (but this is irrelevant until a multivintage option is implemented in the API). Default is NULL, meaning no version parameter is included in the URL.

fileextension

report format requested from the API, sent as fileextension= on each generated report URL. Default "auto" picks the format by report type: "html" for an aggregate multisite report URL (sitenumber 0/"overall" covering more than one site) since HTML renders several times faster and displays directly in the browser tab, but "pdf" for single-site report URLs (the traditional printable community report). Use "html" or "pdf" to force one format for all URLs, or NULL/"" to omit the parameter and get the API's own default. Case/whitespace are normalized; any other value is an error (values are placed in a URL, so arbitrary text is rejected rather than encoded). Only applied to actual API /report URLs, never to app-fallback or ifna links.

...

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 DESCRIPTION field Config/EJAM/url_api).

  • 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.) When a URL sends only ONE site to the API but says sitenumber=N, N identifies which row that site was in the original multisite analysis, so the API can label the report header "Site N" instead of mislabeling every per-site report as Site 1 (Public-Environmental-Data-Partners/EJAM#348) – the per-site URLs this function returns carry that. 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])
} # }