---
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 and the REST Countries 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, and unemployment levels, as well as basic geopolitical information.

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) and [REST Countries](https://restcountries.com/). 
Below is a list of the main functions included in the package:


- `get_country_info()`: Get Key Country Information 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_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* and *REST Countries API*, *covering topics such as population, GDP, CPI, life expectancy, literacy, unemployment, and general country-level indicators*. 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>