---
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.

<div class="tocify-extend-page" data-unique="tocify-extend-page" style="height: 0;"></div>
