API Reference

This page documents all available functions in GeoQuetzal.

pip install geoquetzal

Geography

Functions for accessing Guatemala’s administrative boundaries. Data was downloaded from MINFIN’s Github for administrative boundaries and loads instantly from the library, so no internet connection is required.

`gq.country()`

Returns the country outline of Guatemala as a GeoDataFrame.

import geoquetzal as gq
pais = gq.country()
pais.plot(color="lightgreen", edgecolor="gray")

`gq.departamentos()`

Returns Guatemala’s 22 departments with INE codes and geometry.

Parameters:

Parameter	Type	Description
`name`	`str \| int`	Department name or code (accent-insensitive)
`region`	`str`	Filter by region (e.g. `"V - Central"`)

import geoquetzal as gq

deptos = gq.departamentos()
gq.departamentos("Sacatepequez")   # accent-insensitive
gq.departamentos(3)                # by INE code
gq.departamentos(region="V - Central")

`gq.municipios()`

Returns Guatemala’s 340 municipalities with INE codes and geometry.

Parameters:

Parameter	Type	Description
`departamento`	`str \| int`	Filter by department
`name`	`str \| int`	Return a specific municipality by name or code
`zonas`	`bool`	If `True`, returns Guatemala City’s 22 zones (uses GADM)

import geoquetzal as gq

gq.municipios("Sacatepequez")
gq.municipios(name="Antigua Guatemala")
gq.municipios(name=301)
gq.municipios("Guatemala", zonas=True)

`gq.lagos()`

Returns Guatemala’s two main lakes (Amatitlán and Atitlán) for map overlays.

import geoquetzal as gq

ax = gq.departamentos().plot(color="lightyellow", edgecolor="gray")
gq.lagos().plot(ax=ax, color="lightblue", edgecolor="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 clean the cache:

from geoquetzal.cache import clear_cache
clear_cache()

All microdata functions share the same filter parameters:

Parameter	Type	Description
`departamento`	`str \| int`	Filter by department (downloads only that file)
`municipio`	`str \| int`	Filter by municipality
`geometry`	`str`	Join geometry: `"departamento"` or `"municipio"`

`gq.personas()`

Person-level microdata. 14,901,286 records, 84 variables. Each row is 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).

import geoquetzal as gq

df = gq.personas(departamento="Huehuetenango")
df = gq.personas(municipio="Antigua Guatemala")
df = gq.personas()  # All of Guatemala (~333 MB)

`gq.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).

import geoquetzal as gq

df = gq.hogares(departamento="Sacatepequez")
df = gq.hogares(municipio="Antigua Guatemala")
df = gq.hogares()  # All of Guatemala (~38 MB)

`gq.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).

import geoquetzal as gq

df = gq.viviendas(departamento="Sacatepequez")
df = gq.viviendas()  # All of Guatemala (~30 MB)

`gq.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).

import geoquetzal as gq

df = gq.emigracion(departamento="Huehuetenango")
df = gq.emigracion()  # All of Guatemala (~1.6 MB)

Sub-Municipal Data

`gq.lugares_poblados()`

Pre-aggregated indicators at the lugar poblado (sub-municipal locality) level. 20,254 localities, 200+ columns. Each row represents one lugar poblado.

Data is derived from all three census tables (personas, hogares, viviendas) and stored as counts (not percentages). The correct denominator depends on the type of analysis intended.

Note

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`	`str \| int`	Filter by department
`municipio`	`str \| int`	Filter by municipality
`geometry`	`bool`	If `True`, returns GeoDataFrame with point geometry (centroids)

import geoquetzal as gq

df  = gq.lugares_poblados()
df  = gq.lugares_poblados(departamento="Sacatepéquez") #Loads all populated places from the department of Sacatepéquez
df  = gq.lugares_poblados(municipio="Antigua Guatemala") #Loads all populated places from the municipality of Antigua Guatemala
df = gq.lugares_poblados(lugar_poblado=301001) #Loads populated place 301001 (Antigua Guatemala) data, from the municipality of Antigua Guatemala, Sacatepéquez

gdf = gq.lugares_poblados(geometry=True)

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

`gq.voronoi_lugares_poblados()`

Generates Voronoi polygon approximations as lugar poblado boundaries, clipped to municipio boundaries. These polygons are approximations for choropleth visualization. The INE does not publish official lugar poblado boundaries.

Warning

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`	`str \| int`	Filter by department
`municipio`	`str \| int`	Filter by municipality

import geoquetzal as gq

vor = gq.voronoi_lugares_poblados(municipio="Antigua Guatemala")
vor = gq.voronoi_lugares_poblados(departamento="Sacatepéquez")

# Typical pattern: join with census data for a choropleth
lp  = gq.lugares_poblados(municipio="Antigua Guatemala")
lp  = lp.drop(columns=["nombre", "lat", "longitud", "area"])
gdf = vor.merge(lp, on=["departamento", "municipio", "lugar_poblado"])
gdf["pct_internet"] = gdf["pch9_i_si"] / (gdf["pch9_i_si"] + gdf["pch9_i_no"]) * 100
gdf.plot(column="pct_internet", cmap="YlGnBu", legend=True)

Describe Functions

All describe functions return a DataFrame with all variables if none is specified, or a dict with details for the requested variable.

Function	Dataset
`gq.describe_personas(variable)`	Personas
`gq.describe_hogares(variable)`	Hogares
`gq.describe_viviendas(variable)`	Viviendas
`gq.describe_emigracion(variable)`	Emigración
`gq.describe_lugares_poblados(variable)`	Lugares Poblados

import geoquetzal as gq

gq.describe_personas()
gq.describe_personas("PCP12")
# {'variable': 'PCP12',
#  'etiqueta': '...ethnic self-identification...',
#  'tipo': 'étnica',
#  'valores': {1: 'Maya', 2: 'Garífuna', 3: 'Xinka', ...}}

gq.describe_lugares_poblados("pcp12_maya")
# {'variable': 'pcp12_maya',
#  'etiqueta': 'Conteo: se identifica como Maya',
#  'tipo': 'étnica',
#  'fuente': 'persona'}

Coordinate Reference Systems

from geoquetzal.crs import to_gtm, to_utm16n, suggest_crs

deptos = gq.departamentos()
suggest_crs(deptos)

deptos_gtm = to_gtm(deptos)    # Guatemala Transverse Mercator (national standard)
deptos_utm = to_utm16n(deptos) # UTM Zone 16N (for area/distance calculations)

CRS	Code	Recommended use
WGS 84	`EPSG:4326`	Default, web maps
Guatemala TM (GTM)	`ESRI:103598`	National standard, official maps
UTM Zone 16N	`EPSG:32616`	Area and distance calculations