ripc (version 1.0.0)

ipc_get_areas: Get areas resources from the IPC-CH API

Description

Accesses the areas resources on the IPC-CH API. Contains detailed area and population data. If country, year and/or type parameters are passed, accesses the areas simplified API endpoint and pulls in all areas filtered to those parameters. To get all areas for a specific analysis and period, available on the areas/{id}/{period} advanced API endpoint, pass in id and period. You cannot pass in both sets of parameters.

Usage

ipc_get_areas(
  country = NULL,
  year = NULL,
  type = NULL,
  id = NULL,
  period = NULL,
  return_format = c("csv", "geojson"),
  api_key = NULL,
  tidy_df = TRUE
)

Value

Data frame of IPC and CH analysis at the areas level. Refer to the IPC-CH Public API documentation for details on the returned values, with variables described in full in the extended documentation.

Arguments

country

ISO2 country code.

year

Single numeric year to filter analysis, calculated from the maximum year of current period dates. If NULL, the default, returns data for all years.

type

Single string value of 'A' or 'C', corresponding to food security conditions, either acute or chronic. If NULL, the default, returns data for all types.

id

Analysis ID.

period

Period code, either 'C', 'P', or 'A' for current, projection, and second projection.

return_format

The format that should be returned by the API. Allows "csv" (the default) and "geojson".

api_key

IPC API key. If NULL (the default), looks for IPC_API_KEY in the environment.

tidy_df

If TRUE, returns a tidy data frame wrangled as described in the Tidy section of the documentation. If FALSE, returns the data frame as returned direct from the IPC-CH API.

Tidy

When tidy_df is TRUE, the following changes are made to the initial output to ensure each row represents a single area analysis, and all estimates and values are stored as columns:

1. analysis_period_start and analysis_period_end created as Date columns from the from and to columns respectively, allocating the day of the start and end periods to be the 15th of the month.

2. title column is renamed to be area_name, anl_id to analysis_id, and id and aar_id are changed to area_id.

3. Duplicated rows are removed from the data frame if the return value is CSV, because the duplicates are there due to polygon geometries.

Details

Areas data is the typical unit of analysis in IPC-CH outputs. These are typically administrative units (or clusters of them together). For each area, estimates of the population in each phase is provided and a general phase classification is assigned. Use ipc_get_population() to get detailed population data and classifications for all analysis periods.

See the IPC website and API documentation for more information.

Examples

if (FALSE) { # !is.na(Sys.getenv("IPC_API_KEY", unset = NA))
# get all areas from the simplified API
ipc_get_areas()

# get areas for specific analysis ID and period from advanced API
ipc_get_areas(id = 12856213, period = "P")

# request GeoJSON return
ipc_get_areas(id = 12856213, period = "P", return_format = "geojson")
}