API Reference — R
This page documents all available functions in the GeoQuetzal R package. To install:
remotes::install_github("geoquetzal/geoquetzal-r")Geography
Functions for accessing Guatemala’s administrative boundaries. Data loads instantly from the package — no internet connection required.
country()
Returns the country outline of Guatemala as an sf object.
library(geoquetzal)
pais <- country()
plot(sf::st_geometry(pais), col = "lightgreen", border = "gray")departamentos()
Returns Guatemala’s 22 departments with INE codes and geometry.
Parameters:
| Parameter | Type | Description |
|---|---|---|
name |
character | integer |
Department name or code (accent-insensitive) |
region |
character |
Filter by region (e.g. "V - Central") |
library(geoquetzal)
deptos <- departamentos()
departamentos("Sacatepequez") # accent-insensitive
departamentos(3) # by INE code
departamentos(region = "V - Central")municipios()
Returns Guatemala’s 340 municipalities with INE codes and geometry.
Parameters:
| Parameter | Type | Description |
|---|---|---|
departamento |
character | integer |
Filter by department |
name |
character | integer |
Return a specific municipality by name or code |
library(geoquetzal)
municipios("Sacatepequez")
municipios(name = "Antigua Guatemala")
municipios(name = 301)lagos()
Returns Guatemala’s two main lakes (Amatitlán and Atitlán) for map overlays.
library(geoquetzal)
library(ggplot2)
ggplot() +
geom_sf(data = departamentos(), fill = "lightyellow", color = "gray") +
geom_sf(data = lagos(), fill = "lightblue", color = "steelblue")Census Microdata
Functions for accessing the XII National Population and Housing Census 2018 microdata (INE). Data is downloaded as Parquet files from GitHub Releases and cached locally.
To manage the cache:
gq_cache_dir() # View cache location
gq_clear_cache() # Clear the cache
gq_set_cache("/custom/path") # Change cache locationAll microdata functions share the same filter parameters:
| Parameter | Type | Description |
|---|---|---|
departamento |
character | integer |
Filter by department (downloads only that file) |
municipio |
character | integer |
Filter by municipality (downloads the parent department’s file) |
personas()
Person-level microdata. 14,901,286 records, 84 variables. Each row represents one person.
Key variables: sex (PCP6), age (PCP7), ethnic self-identification (PCP12), Mayan linguistic community (PCP13), mother tongue (PCP15), disability (PCP16_A–PCP16_F), education level (PCP17_A), literacy (PCP22), technology access (PCP26_A–PCP26_C), employment (PCP27), fertility (PCP35–PCP39).
library(geoquetzal)
df <- personas(departamento = "Huehuetenango")
df <- personas(municipio = "Antigua Guatemala")
df <- personas() # All of Guatemala (~333 MB)hogares()
Household microdata. 3,275,931 records, 37 variables. Each row represents one household.
Key variables: water source (PCH4), sanitation (PCH5), electricity (PCH8), household appliances — radio, TV, fridge, internet, car (PCH9_A–PCH9_M), cooking fuel (PCH14), remittances (PCH15).
library(geoquetzal)
df <- hogares(departamento = "Sacatepequez")
df <- hogares(municipio = "Antigua Guatemala")
df <- hogares() # All of Guatemala (~38 MB)viviendas()
Housing unit microdata. ~3,300,000 records, 11 variables. Each row represents one housing unit.
Key variables: housing type (PCV1), wall material (PCV2), roof (PCV3), condition (PCV4), floor (PCV5).
library(geoquetzal)
df <- viviendas(departamento = "Sacatepequez")
df <- viviendas() # All of Guatemala (~30 MB)emigracion()
International emigration records. 242,203 records, 11 variables. Each row represents one person who emigrated from a household.
Key variables: sex (PEI3), age at departure (PEI4), year of departure (PEI5).
library(geoquetzal)
df <- emigracion(departamento = "Huehuetenango")
df <- emigracion() # All of Guatemala (~1.6 MB)Sub-Municipal Data
lugares_poblados()
Pre-aggregated indicators at the lugar poblado (sub-municipal locality) level. 20,254 localities, 200+ columns. Each row represents one lugar poblado.
Lugares poblados with codes ending in 999 (e.g. 102999) represent unnamed informal settlements (“Otros Lugares Poblados”) with NULL coordinates. They are included in the data but cannot be mapped.
Parameters:
| Parameter | Type | Description |
|---|---|---|
departamento |
character | integer |
Filter by department (downloads only that file) |
municipio |
character | integer |
Filter by municipality |
lugar_poblado |
integer |
6-digit code (e.g. 301001L) |
library(geoquetzal)
df <- lugares_poblados()
df <- lugares_poblados(departamento = "Sacatepéquez")
df <- lugares_poblados(municipio = "Antigua Guatemala")
df <- lugares_poblados(lugar_poblado = 301001L)Available columns by topic:
| Topic | Column prefix | Source |
|---|---|---|
| Scalars (population, PEA, years of education) | poblacion_total, pea_total, aneduca_promedio… |
persona |
| Ethnic self-identification | pcp12_maya, pcp12_ladino… |
persona |
| Mayan linguistic community | pcp13_kiche, pcp13_mam… |
persona |
| Mother tongue | pcp15_espanol, pcp15_kiche… |
persona |
| Disability | pcp16_a_sin_dificultad… |
persona |
| Education level | pcp17_a_ninguno, pcp17_a_primaria… |
persona |
| Literacy | pcp22_alfabeto, pcp22_no_alfabeto |
persona |
| Employment | pcp30_1d_agropecuarios… |
persona |
| Housing type | pcv1_casa_formal, pcv1_rancho… |
vivienda |
| Wall material | pcv2_block, pcv2_adobe… |
vivienda |
| Floor material | pcv5_tierra, pcv5_torta_cemento… |
vivienda |
| Water source | pch4_tuberia_dentro, pch4_rio… |
hogar |
| Sanitation | pch5_inodoro_red_drenajes… |
hogar |
| Electricity | pch8_red_electrica, pch8_candela… |
hogar |
| Household appliances | pch9_i_si (internet), pch9_m_si (car)… |
hogar |
| Cooking fuel | pch14_lena, pch14_gas_propano… |
hogar |
| Remittances | pch15_si, pch15_no |
hogar |
| Emigration since 2002 | pei1_si, pei1_no |
hogar |
voronoi_lugares_poblados()
Generates Voronoi polygon approximations as lugar poblado boundaries, clipped to municipio boundaries. These polygons are approximations for choropleth visualization — INE does not publish official lugar poblado boundaries.
Lugares poblados with NULL coordinates (codes ending in 999) are automatically excluded. Municipios with only one lugar poblado return the full municipio polygon.
Parameters:
| Parameter | Type | Description |
|---|---|---|
departamento |
character | integer |
Filter by department |
municipio |
character | integer |
Filter by municipality |
library(geoquetzal)
library(mapview)
vor <- voronoi_lugares_poblados(municipio = "Antigua Guatemala")
vor <- voronoi_lugares_poblados(departamento = "Sacatepéquez")
# Typical pattern: join with census data for a choropleth
lp <- lugares_poblados(municipio = "Antigua Guatemala")
lp <- lp[, !names(lp) %in% c("nombre", "lat", "longitud", "area")]
gdf <- merge(vor, lp, by = c("departamento", "municipio", "lugar_poblado"))
gdf$pct_internet <- gdf$pch9_i_si / (gdf$pch9_i_si + gdf$pch9_i_no) * 100
mapview(gdf, zcol = "pct_internet",
col.regions = RColorBrewer::brewer.pal(9, "YlGnBu"),
layer.name = "% with Internet")Describe Functions
All describe functions return a data.frame with all variables if none is specified, or a list with details for the requested variable.
| Function | Dataset |
|---|---|
describe_personas(variable) |
Personas |
describe_hogares(variable) |
Hogares |
describe_viviendas(variable) |
Viviendas |
describe_emigracion(variable) |
Emigración |
describe_lugares_poblados(variable) |
Lugares Poblados |
library(geoquetzal)
describe_personas()
describe_personas("PCP12")
# $variable: "PCP12"
# $etiqueta: "...ethnic self-identification..."
# $tipo: "étnica"
# $valores: list("1" = "Maya", "2" = "Garífuna", "3" = "Xinka", ...)
describe_lugares_poblados("pcp12_maya")
# $variable: "pcp12_maya"
# $etiqueta: "Conteo: se identifica como Maya"
# $tipo: "étnica"
# $fuente: "persona"