Skip to contents

Using the EJAM API

Source: vignettes/dev-api.Rmd
dev-api.Rmd

This is a short overview. For the authoritative and most current details, see:

What the API is

Besides the R package and the web app, EJAM is available as a hosted REST API that returns EJScreen-style community reports (and the underlying data) for a point, a set of points, a polygon, or US Census areas (FIPS). It runs the same engine as the package, so an API report matches what ejamit() / ejam2report() would produce locally.

Reaching it from R

Two functions wrap the API:

  • ejamapi() – builds the request, calls the API, and returns the report or data.
  • url_ejamapi() – builds the API request URL(s) without calling them (useful for a table of shareable links, or to open one in a browser).
ejamapi(lat = 33, lon = -112, radius = 3)              # get a report or data back
url_ejamapi(lat = c(33, 34), lon = c(-112, -114))      # just build the URL(s)

The API base URL – and a friendlier branded alias such as https://api.ejanalysis.com – are described in the EJAM-API README. You do not normally need to set the base URL yourself.

Deep linking: launch the app pre-loaded

Separately from the data API, the EJAM web app can be launched pre-loaded with a set of places by opening it with launch query parameters in the URL – the basis for the EJScreen “Send to EJAM” hand-off, which moves a selection straight into the full app. Points and FIPS codes travel directly in the URL; larger sets and drawn polygons use a token handoff (POST /handoff returns a token, and the app fetches the places back from GET /handoff/<token> at startup) so they are not limited by URL length. Use url_ejamapp() to build these launch URLs from R.

For the launch-URL vocabulary and the handoff endpoints, see the Defaults and Custom Settings for the Web App article and the EJAM-API README.

A few notes on parameters

  • Provide one input type per request: points (lat/lon), or fips, or shape.
  • buffer is a synonym for radius; fileextension is html or pdf.
  • For an aggregate multisite report over several places at once, pass sitenumber=0 (the default for a single site is sitenumber=1; a positive N reports on just the Nth site). Many or large polygons that would exceed a GET URL’s length can be sent via a POST /report request. See the parameter notes in the EJAM-API README.

For anything not covered here, the EJAM-API README is the source of truth, and ?ejamapi / ?url_ejamapi document the R interface.