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

# Introduction

The `MexicoDataAPI` package provides a unified interface to access open data from the **World Bank API**, **REST Countries API**, and **Nager.Date API**, with a focus on Mexico. It allows users to retrieve up-to-date information on topics such as economic indicators, population figures, literacy rates, unemployment levels, basic geopolitical information, and official public holidays.

In addition to API-access functions, the package includes a set of curated datasets related to **Mexico**. These cover areas such as air quality monitoring, state-level income surveys, postal abbreviations, election results, and regional forest classification.

`MexicoDataAPI` is intended to support users working with data related to Mexico by integrating international API sources with selected datasets from national and academic origins, in a single R package.


## Functions for MexicoDataAPI

The `MexicoDataAPI` package provides several core functions to access real-time and structured information about Mexico from public APIs such as the [World Bank API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392), [REST Countries](https://restcountries.com/), and [Nager.Date API](https://date.nager.at/Api).


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


- `get_country_info_mx()`: Get Key Country Information about Mexico from the REST Countries API

- `get_mexico_cpi()`: Get Mexico's Consumer Price Index (2010 = 100) from World Bank  

- `get_mexico_gdp()`: Get Mexico's GDP (Current US$) from World Bank 

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

- `get_mexico_life_expectancy()`: Get Mexico's Life Expectancy from World Bank 

- `get_mexico_literacy_rate()`: Get Mexico's Literacy Rate (Age 15+) from World Bank 

- `get_mexico_population()`: Get Mexico's Population (Total) from World Bank 

- `get_mexico_unemployment()`: Get Mexico's Unemployment Rate (%) from World Bank 

- `view_datasets_MexicoDataAPI()`: Lists all curated datasets included in the `MexicoDataAPI` package


These functions allow users to access high-quality and structured information on `Mexico`, 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 `MexicoDataAPI` in practical scenarios.

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

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


mexico_gdp <- head(get_mexico_gdp())

print(mexico_gdp)

```


### Mexico's Life Expectancy from World Bank 2022 - 2017

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

life_expectancy <- head(get_mexico_life_expectancy())

print(life_expectancy)

```


### Mexico's Population (Total) from World Bank 2022 - 2017

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

mexico_population <- head(get_mexico_population())

print(mexico_population)

```



### Average Household Income by Education Level (2008)

```{r mexico-income-plot, message=FALSE, warning=FALSE, fig.width=7, fig.height=5}


# Summary of average income by education level
avg_income_by_education <- mex_income_2008_tbl_df %>%
  group_by(education) %>%
  summarise(avg_income = mean(income, na.rm = TRUE)) %>%
  arrange(desc(avg_income))

# Plot
ggplot(avg_income_by_education, aes(x = reorder(education, avg_income), y = avg_income)) +
  geom_col(fill = "#0072B2") +
  coord_flip() +
  labs(
    title = "Average Household Income by Education Level (2008)",
    x = "Education Level",
    y = "Average Income (MXN)"
  ) +
  theme_minimal()


```



## Dataset Suffixes

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

- `_df`: A standard data frame.

- `_tbl_df`: A tibble data frame object.

- `_chr`: A character object.


## Datasets Included in MexicoDataAPI

In addition to API access functions, `MexicoDataAPI` provides several preloaded datasets related to Mexico’s environment, demographics, and public data. Here are some featured examples:

- `mexico_elections_df`: Data frame containing a subset of the 2012 Mexico Elections Panel Study.

- `mex_income_2016_tbl_df`: Tibble containing household-level income data and associated demographic characteristics from the 2016 ENIGH (Household Income and Expenditure Survey).

- `mexico_abb_chr`: Character vector containing the official two- or three-letter
postal abbreviations for the 32 federal entities of Mexico.


## Conclusion

The `MexicoDataAPI` package provides a comprehensive interface to access open data about **Mexico** through RESTful APIs and curated datasets. It includes functions to retrieve real-time information from the **World Bank API**, **REST Countries API**, and **Nager.Date API**, covering topics such as population, GDP, CPI, life expectancy, literacy, unemployment, general country-level indicators, and official public holidays. In addition, the package offers curated datasets related to air quality monitoring stations, pollution zones, state-level income surveys for 2008 and 2016, postal abbreviations, election studies, and ecological data from the Chiapas dry forests. Together, these resources support research, teaching, and analysis focused on Mexico's economic, environmental, and sociopolitical landscape.


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