---
title: "ColombiAPI: Access Colombian Data via APIs and Curated Datasets"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{ColombiAPI: Access Colombian 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(ColombiAPI)
library(dplyr)
library(ggplot2)
```


# Introduction 

The `ColombiAPI` package provides a comprehensive interface to access diverse public data about **Colombia** through multiple APIs and curated datasets. The package integrates three different APIs: **API-Colombia** for Colombian-specific data including geography, culture, tourism, and government information; **World Bank API** for economic and demographic indicators; and **Nager.Date API** for public holidays. This allows users to retrieve up-to-date or historical information on topics such as geographic locations, cultural attractions, economic indicators, demographic data, and public holidays.

In addition to API-access functions, the package includes curated datasets covering a wide range of topics, including **Bogota** air stations, business and holiday dates, public schools, Colombian coffee exports, cannabis licenses, **Medellin** rainfall, malls in **Bogota**, indigenous languages, student admissions and school statistics, forest liana mortality, municipal and regional data, connectivity and digital infrastructure, program graduates, vehicle counts, international visitors, and GDP projections. These datasets provide a rich and multifaceted view of Colombian social, economic, environmental, and technological information.

`ColombiAPI` is designed to support users working with data related to **Colombia** by integrating international RESTful APIs with Colombian-specific APIs and structured, reliable datasets from public, academic, and government sources into a single, easy-to-use R package.


## ColombiAPI Functions

The `ColombiAPI` package provides several core functions to access real-time or historical information about **Colombia** from public APIs such as **API-Colombia**, **World Bank API**, and **Nager.Date**.

Below is a list of the main functions included in the package:

- `get_colombia_airports()`: Get Colombia's Airports from API Colombia.

- `get_colombia_attractions()`: Get All Touristic Attractions of Colombia from API Colombia.

- `get_colombia_child_mortality()`: Get Colombia's Under-5 Mortality Rate from World Bank.

- `get_colombia_cities()`: Get All Cities of Colombia from API Colombia.

- `get_colombia_cpi()`: Get Colombia's Consumer Price Index (2010 = 100) from World Bank.

- `get_colombia_departments()`: Get Colombia's Departments from API Colombia.

- `get_colombia_energy_use()`: Get Colombia's Energy Use (kg of oil equivalent per capita) from World Bank.

- `get_colombia_gdp()`: Get Colombia's GDP (current US$) from World Bank.

- `get_colombia_holidays()`: Get official public holidays in Colombia for a given year, e.g., `get_colombia_holidays(2025)`.

- `get_colombia_hospital_beds()`: Get Colombia's Hospital Beds (per 1,000 people) from World Bank.

- `get_colombia_invasive_species()`: Get Invasive Species of Colombia from API Colombia.

- `get_colombia_life_expectancy()`: Get Colombia's Life Expectancy at Birth (Total, Years) from World Bank.

- `get_colombia_literacy_rate()`: Get Colombia's Adult Literacy Rate from World Bank.

- `get_colombia_native_communities()`: Get Native Communities of Colombia from API Colombia.

- `get_colombia_natural_areas()`: Get Natural Areas of Colombia from API Colombia.

- `get_colombia_population()`: Get Colombia's Total Population from World Bank.

- `get_colombia_presidents()`: Get Colombia's Presidents from API Colombia.

- `get_colombia_radios()`: Get Radios of Colombia from API Colombia.

- `get_colombia_regions()`: Get Colombia's Regions from API Colombia.

- `get_colombia_typical_dishes()`: Get Typical Dishes of Colombia from API Colombia.

- `get_colombia_unemployment()`: Get Colombia's Unemployment Rate (Total) from World Bank.

- `view_datasets_ColombiAPI()`: View available curated datasets included in ColombiAPI.


These functions allow users to access high-quality and structured information on **Colombia**, which can be combined with tools like **dplyr** and **ggplot2** to support a wide range of data analysis, visualization, and research tasks. In the following sections, you’ll find examples on how to work with `ColombiAPI` in practical scenarios.

### Colombia's GDP (Current US$) from World Bank 2022 - 2017

```{r colombia-gdp,echo = TRUE,message = FALSE,warning = FALSE,results = 'markup'}


colombia_gdp <- head(get_colombia_gdp())

print(colombia_gdp)

```


### Colombia's Life Expectancy at Birth from World Bank 2022 - 2017

```{r colombia-life-expectancy,echo = TRUE,message = FALSE,warning = FALSE,results = 'markup'}

colombia_life_expectancy <- head(get_colombia_life_expectancy())

print(colombia_life_expectancy)

```


### Colombia's Total Population from World Bank 2022 - 2017

```{r colombia-population,echo = TRUE,message = FALSE,warning = FALSE,results = 'markup'}

colombia_population <- head(get_colombia_population())

print(colombia_population)

```


## Monthly Average Rainfall in Medellin

```{r colombia-rainfall, message=FALSE, warning=FALSE, fig.width=9, fig.height=5}

Medellin_rain_tbl_df %>%
  group_by(month) %>%
  summarise(mean_rainfall = mean(rainfall, na.rm = TRUE), .groups = "drop") %>%
  ggplot(aes(x = month, y = mean_rainfall)) +
  geom_line(size = 1, color = "steelblue") +
  geom_point(size = 2, color = "darkred") +
  labs(
    title = "Climatological Monthly Average Rainfall in Medellin",
    subtitle = "Each point represents the long-term mean rainfall for that month, averaged across all years",
    x = "Month",
    y = "Mean Rainfall (mm)"
  ) +
  theme_minimal()



```


### Dataset Suffixes

Each dataset in `ColombiAPI` is labeled with a `suffix` to indicate its type and structure:

- `_df`: A standard data frame.

- `_tbl_df`: A tibble, a modern version of a data frame with better formatting and functionality.

- `_Date`: An object of type Date.


### Datasets Included in ColombiAPI

In addition to API functions, `ColombiAPI` includes several preloaded datasets that provide valuable insights into various aspects of `Colombia`:

- `Bogota_airstations_df`: A data frame containing coordinates of air quality monitoring stations in Bogota.

- `Bogota_business_Date`: A Date object listing official business dates in Bogota. 

- `Colombia_coffee_tbl_df`: A tibble with details of Colombian coffee export and import for the year 2016.


## Viewing All Available Datasets 

The `ColombiAPI` package includes a built-in function, `view_datasets_ColombiAPI()`, which allows users to view a comprehensive list of all datasets available in the package directly from the console:

```{r view_datasets}

view_datasets_ColombiAPI()

```


## Conclusion
The `ColombiAPI` package provides a comprehensive and powerful interface for accessing both real-time data through public APIs and a wide range of curated datasets about **Colombia**. By integrating multiple data sources — including **API-Colombia** for Colombian-specific data on geography, culture, tourism, and government information; **World Bank API** for economic and demographic indicators; and **Nager.Date API** for public holidays — the package allows users to explore **Colombia** from multiple perspectives in a structured and consistent way.

In addition to API-driven data, `ColombiAPI` offers preloaded curated datasets covering diverse topics such as **Bogota** air stations, business and holiday dates, public schools, Colombian coffee exports, cannabis licenses, **Medellin** rainfall, malls in **Bogota**, indigenous languages, student admissions and school statistics, forest liana mortality, municipal and regional data, connectivity and digital infrastructure, program graduates, vehicle counts, international visitors, and GDP projections. This dual approach of combining live API data with curated datasets empowers users to analyze Colombia’s social, economic, environmental, technological, and cultural landscape in greater depth.

Designed to support reproducible research, education, policy analysis, and data journalism, `ColombiAPI` makes it possible to seamlessly integrate Colombian data into the R ecosystem, ensuring accessibility, reliability, and clarity for a wide range of applications.


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