get_data {SUNGEO}

Download data from SUNGEO server

Description

Function to download data files through the SUNGEO API. Function produces a data.table object, corresponding to the user's choice of countries, topics, sources, and spatial and temporal units.

Usage

get_data(
  country_names = NULL,
  country_iso3 = NULL,
  geoset = "GADM",
  geoset_yr = 2018,
  space_unit = "adm1",
  time_unit = "year",
  topics = NULL,
  year_min = 1990,
  year_max = 2017,
  print_url = TRUE,
  print_time = TRUE,
  error_stop = FALSE,
  by_topic = TRUE,
  skip_missing = TRUE,
  cache_param = FALSE,
  short_message = TRUE
)

Arguments

country_names

Country name(s). Character string (single country) or vector of character strings (multiple countries).

country_iso3

Country code (ISO 3166-1 alpha-3). Character string (single country) or vector of character strings (multiple countries).

geoset

Name of geographic boundary set. Can be one of "GADM" (Database of Global Administrative Areas), "GAUL" (Global Administrative Unit Layers), "geoBoundaries", "GRED" (GeoReferenced Electoral Districts Datasets), "HEXGRID" (SUNGEO Hexagonal Grid), "MPIDR" (Max Planck Institute for Demographic Research Population History GIS Collection), "NHGIS" (National Historical Geographic Information System), "PRIOGRID" (PRIO-GRID 2.0), "SHGIS" (SUNGEO Historical GIS). Default is "GADM". Character string.

geoset_yr

Year of geographic boundaries. See get_info()['geosets'] for availability. Default is 2018. Integer.

space_unit

Geographic level of analysis. Can be one of "adm0" (country), "adm1" (province), "adm2" (district), "cst" (GRED electoral constituency), "hex05" (SUNGEO Hexagonal Grid cell), "prio" (PRIO-GRID cell). See get_info()['geosets'] for availability by geoset, country and topic. Default is "adm1". Character string.

time_unit

Temporal level of analysis. Can be one of "year", "month", "week". See get_info()['topics'] for availability by topic. Default is "year". Character string.

topics

Data topics. See get_info()['summary'] for full list. Character string (single topic) or vector of character strings (multiple topics).

year_min

Time range of requested data: start year. See get_info()['topics'] for availability by topic. Default is 1990. Integer.

year_max

Time range of requested data: end year. See get_info()['topics'] for availability by topic. Default is 2017. Integer.

print_url

Print url string of requested data to console? Default is TRUE. Logical.

print_time

Print processing time for API query to console? Default is TRUE. Logical.

error_stop

Error handling. If TRUE, function terminates request if an error is encountered. If FALSE, error is skipped and error message is recorded in a new message column. Default is FALSE. Logical.

by_topic

Break query down by topic and country? If TRUE, a separate request is sent to the API for each country and topic, and the results are combined on the client side. This ensures that data that are available for some, but not all countries are returned, rather than resulting in a failed request. If FALSE, a single request is sent to the API for all countries and topics, and the results are combined on the server side. Only data that are available for all countries are returned. Default is TRUE. Logical.

skip_missing

Skip missing data topics? If TRUE, missing data topics are skipped, columns are populated with NAs, and corresponding error message is recorded in a new message column. If FALSE, returns NULL results for missing topics. Default is TRUE. Logical.

cache_param

Store cached query on server? This can speed up processing for repeated queries. Default is FALSE. Logical.

short_message

Shorten error messages? If TRUE, a short, informative error message is recorded in the message column. If FALSE, full error message is recorded. Default is TRUE. Logical.

Value

data.table object, with requested data from SUNGEO API.

See Also

get_info

Examples

# Single country, single topic
## Not run: 
out_1 <- get_data(country_name="Afghanistan",topics="Demographics:Population:GHS")
out_1

## End(Not run)

## Not run: 
out_2 <- get_data(
	country_name=c("Afghanistan","Moldova"),
	topics=c("Demographics:Ethnicity:EPR","Demographics:Population:GHS"))
out_2

## End(Not run)

# Other boundary sets, spatial and time units
## Not run: 
out_3 <- get_data(
	country_name="Albania",
	topics="Weather:AirTemperatureAndPrecipitation:NOAA",
	geoset="GAUL",geoset_yr=1990,space_unit="adm2",time_unit="month",
	year_min=1990,year_max=1991)
out_3

## End(Not run)