--- title: "ChileDataAPI: Access Chilean Data via APIs and Curated Datasets" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{ChileDataAPI: Access Chilean Data via APIs and Curated Datasets} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ```{r setup} library(ChileDataAPI) library(ggplot2) library(dplyr) ``` # Introduction The `ChileDataAPI` package provides a unified interface to access open data from the *FINDIC API* and the *REST Countries API*, with a focus on Chile. It allows users to easily retrieve up-to-date time series data on financial indicators such as the **UF, UTM, Dollar, Euro, Yen, Copper price per pound, Bitcoin, and the IPSA index**, as well as international metadata on countries via standardized API calls. All API-based functions return data as tidy tibble objects, making them ready for immediate use in data pipelines. The financial indicator functions, such as `get_chile_dollar()`, `get_chile_uf()`, and `get_chile_bitcoin()`, provide real-time series of daily or monthly values, with each row representing a timestamped observation. This makes `ChileDataAPI` a valuable tool for working with economic time series data in a reproducible manner. In addition to API-access functions, the package includes a collection of curated datasets related to *Chile*, covering diverse topics such as: - `Demographics`: sample microdata from the 2017 Chilean Census - `Elections`: data from the 2021 presidential elections and national plebiscites - `Public health`: individual-level records from national health surveys - `Human rights`: detailed accounts of violations during the Pinochet regime - `Seismology`: geolocated data on earthquakes in *Chile* - `Geopolitical data`: official territorial codes for communes, provinces, and regions - `Environmental history`: tree-ring based climate series from Malleco forest `ChileDataAPI` is designed to support research, teaching, and data analysis focused on *Chile* by integrating public RESTful APIs with high-quality, domain-specific datasets into a single, easy-to-use R package. ## Functions for ChileDataAPI The `ChileDataAPI` package provides several core functions to access real-time and structured information about Chile from public APIs such as [FINDIC](https://findic.cl/) and [REST Countries](https://restcountries.com/). Below is a list of the main functions included in the package: - `get_chile_bitcoin()`: Retrieves the daily Bitcoin price in Chilean Pesos over the last month. - `get_chile_copper_pound()`: Returns historical daily copper prices (per pound). - `get_chile_dollar()`: Provides the exchange rate of the U.S. Dollar in CLP. - `get_chile_euro()`: Provides the exchange rate of the Euro in CLP. - `get_chile_ipsa()`: Retrieves daily values of the IPSA (Chile's stock market index). - `get_chile_uf()`: Returns daily values of the Unidad de Fomento (UF). - `get_chile_utm()`: Returns monthly values of the Unidad Tributaria Mensual (UTM). - `get_chile_yen()`: Provides the exchange rate of the Japanese Yen in CLP. - `get_country_info(name)`: Get essential information about Chile or any other country by its full name Example: *get_country_info("Chile")*,*get_country_info("chile")*,*get_country_info("Peru")* - `view_datasets_ChileDataAPI()`: Lists all curated datasets included in the `ChileDataAPI` package These functions return real-time data in tidy `tibble` format and represent **time series** that are updated daily or monthly depending on the source. These functions allow users to access high-quality and structured information on `Chile`, which can be combined with tools like `dplyr`, `tidyr`, and `ggplot2` to support a wide range of data analysis and visualization tasks. In the following sections, you’ll find examples on how to work with `ChileDataAPI` in practical scenarios. ### Get Observed Copper Price per Pound ```{r chile-copper,echo = TRUE,message = FALSE,warning = FALSE,results = 'markup'} chile_copper_price <- head(get_chile_copper_pound(),n=10) print(chile_copper_price) ``` ### Get exchange rate of the U.S. Dollar in CLP ```{r chile-dollar,echo = TRUE,message = FALSE,warning = FALSE,results = 'markup'} chile_dollar_price <- head(get_chile_dollar(),n=10) print(chile_dollar_price) ``` ### Get exchange rate of the Euro in CLP. ```{r chile-euro,echo = TRUE,message = FALSE,warning = FALSE,results = 'markup'} chile_euro_price <- head(get_chile_euro(),n=10) print(chile_euro_price) ``` ### Systolic Blood Pressure by Age and Gender ```{r chile-health-plot, message=FALSE, warning=FALSE, fig.width=7, fig.height=5} # Clean data: remove missing values from key variables health_clean <- chile_health_survey_df %>% filter(!is.na(age), !is.na(pas), !is.na(male)) # Create gender variable health_clean <- health_clean %>% mutate(gender = ifelse(male == 1, "Male", "Female")) # Plot: Systolic Blood Pressure vs Age by Gender ggplot(health_clean, aes(x = age, y = pas, color = gender)) + geom_point(alpha = 0.4) + geom_smooth(method = "lm", se = FALSE) + labs( title = "Systolic Blood Pressure (PAS) by Age and Gender", x = "Age (years)", y = "Systolic Blood Pressure (mm Hg)", color = "Gender" ) + theme_minimal() ``` ## Dataset Suffixes Each dataset in `ChileDataAPI` is labeled with a *suffix* to indicate its structure and type: - `_df`: A standard data frame. - `_ts`: A time series object. - `_tbl_df`: A tibble data frame object. ## Datasets Included in ChileDataAPI In addition to API access functions, `ChileDataAPI` provides several curated datasets offering valuable insights into *Chile*’s recent history, population health, territorial divisions, electoral processes, and seismic activity. Here are some featured examples: - `census_chile_2017_df`: Data frame containing microdata from the 2017 Chilean census, specifically from the commune of San Pablo. The dataset includes 7,512 observations, all variable names and data values are in Spanish. - `chile_earthquakes_tbl_df`: Tibble containing information about significant (perceptible) earthquakes that occurred in Chile from January 1st, 2012 to the present. - `malleco_tree_rings_ts`: Time series object (`ts`) containing the average annual tree ring width, measured in millimeters, for Araucaria Araucana trees located in the Malleco region of Chile. ## Conclusion The `ChileDataAPI` package provides a robust set of tools to access open data about *Chile* through *RESTful APIs* and curated datasets. It includes functions to retrieve real-time financial indicators—such as the value of the dollar, euro, yen, copper, UF, UTM, and Bitcoin—via the *FINDIC API*, as well as international country information through the *REST Countries API*. Additionally, it offers preloaded datasets covering *Chile*’s recent history and socio-political context, including the 2017 census sample, the 2021 presidential election, public health survey data, territorial codes, seismic events, and records of human rights violations during the Pinochet regime.