The ripc functions provide access to API endpoints detailed in the IPC-CH Public API documentation. The documentation should be referred to in order to better understand the API calls themselves (under the simplified and advanced documentation sections), and the returned data. For ease of the user, a table to match up the simplified and advanced API endpoints with ripc functions is below.
In general, the same functions can access both API endpoints, but the simplified endpoints are accessed with optional parameters while the advanced endpoints are accessed when IDs and/or periods are explicitly passed.
Please refer to the IPC API
documentation to learn how to generate a token for the API you can
use to access the data. This API key should be stored in your
IPC_API_KEY. You can easily add this to your
environment by adding the following line to your
file, easily accessed using
IPC_API_KEY="API key here"
Make sure that your API key is granted access to the resources you need.
Data coming from the IPC API isn’t immediately joinable, with varying
naming conventions for geographical name/ID columns. Outputs from the
ripc functions are wrangled to ease the joining of datasets together by
standardizing some column names and keeping the data in a tidy format.
You can specify
tidy_df = FALSE for any
ipc_get_...() function to return directly what the IPC-CH
Public API returns.
The tidy format means that a specific analysis for a period (current, projection, or second projection) and geography (area/point, group, or country) are stored in a single row, with columns containing the relevant metadata, phase classification, and population figures. Data from mixed levels of geography are not stored in the same dataset.
While full documentation of output data can be derived from the IPC API schema documentation, key changes made to the outputs to create tidy data are documented below.
analysis_idis used across all datasets to identify the ID for a specific analysis.
area_nameis used to identify area and point IDs across the datasets.
group_namefor groups in the same manner.
titlerefers solely to the title of the analysis.
phase#_pctrefer to the number of population and percent of population in each phase, respectively.
analysis_period_endare created to be easy to access and manipulate date columns (rather than strings) in the dataset, representing the start of an analysis period (1st day of the first month) and end of an analysis period (last day of the last month).
Each exported function from ripc has a Tidy section describing the wrangling done.