Referencia de la API

Esta página documenta todas las funciones disponibles en GeoQuetzal. Para instalar la librería:

pip install geoquetzal

Geografía

Funciones para acceder a los límites administrativos de Guatemala. Los datos fueron descargados del Github de los límites geográficos disponibles del Ministerio de Finanzas (MINFIN) y se cargan instantáneamente desde la librería, not del Github del MINFIN, por lo que no requieren conexión a Internet.

`gq.country()`

Retorna el contorno del país de Guatemala como un GeoDataFrame.

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

`gq.departamentos()`

Retorna los 22 departamentos de Guatemala con sus códigos INE y geometría.

Parámetros:

Parámetro	Tipo	Descripción
`name`	`str \| int`	Nombre o código del departamento (insensible a acentos)
`region`	`str`	Filtra por región (ej. `"V - Central"`)

import geoquetzal as gq

# Todos los departamentos
deptos = gq.departamentos()

# Por nombre (con o sin acentos)
gq.departamentos("Sacatepequez")
gq.departamentos("Sacatepéquez")

# Por código INE
gq.departamentos(3)

# Por región
gq.departamentos(region="V - Central")

`gq.municipios()`

Retorna los 340 municipios de Guatemala con sus códigos INE y geometría.

Parámetros:

Parámetro	Tipo	Descripción
`departamento`	`str \| int`	Filtra por departamento
`name`	`str \| int`	Retorna un municipio específico por nombre o código
`zonas`	`bool`	Si `True`, retorna las 22 zonas de la Ciudad de Guatemala (usa GADM)

import geoquetzal as gq

# Todos los municipios de un departamento
gq.municipios("Sacatepequez")

# Un municipio específico
gq.municipios(name="Antigua Guatemala")
gq.municipios(name=301)

# Zonas de Guatemala City
gq.municipios("Guatemala", zonas=True)

`gq.lagos()`

Retorna los dos principales lagos de Guatemala (Amatitlán y Atitlán) para superposición en mapas.

import geoquetzal as gq

ax = gq.departamentos().plot(color="lightyellow", edgecolor="gray")
gq.lagos().plot(ax=ax, color="lightblue", edgecolor="steelblue")

Microdatos Censales

Funciones para acceder a los microdatos del XII Censo Nacional de Población y VII de Vivienda 2018 (INE). Los datos se descargan en formato Parquet desde GitHub Releases y se almacenan en caché localmente. Para limpiar el caché:

from geoquetzal.cache import clear_cache
clear_cache()

Todas las funciones de microdatos comparten los mismos parámetros de filtro:

Parámetro	Tipo	Descripción
`departamento`	`str \| int`	Filtra por departamento (descarga solo ese archivo)
`municipio`	`str \| int`	Filtra por municipio (descarga el archivo del departamento padre)
`geometry`	`str`	Une geometría: `"departamento"` o `"municipio"`

`gq.personas()`

Microdatos a nivel de persona. 14,901,286 registros, 84 variables. Cada fila representa una persona.

Variables principales: sexo (PCP6), edad (PCP7), autoidentificación étnica (PCP12), comunidad lingüística maya (PCP13), lengua materna (PCP15), discapacidad (PCP16_A–PCP16_F), escolaridad (PCP17_A), alfabetismo (PCP22), acceso a tecnología (PCP26_A–PCP26_C), empleo (PCP27), fecundidad (PCP35–PCP39).

import geoquetzal as gq

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

`gq.hogares()`

Microdatos a nivel de hogar. 3,275,931 registros, 37 variables. Cada fila representa un hogar.

Variables principales: fuente de agua (PCH4), saneamiento (PCH5), electricidad (PCH8), equipamiento del hogar — radio, TV, refrigeradora, internet, carro (PCH9_A–PCH9_M), combustible para cocinar (PCH14), remesas (PCH15).

import geoquetzal as gq

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

`gq.viviendas()`

Microdatos a nivel de vivienda. ~3,300,000 registros, 11 variables. Cada fila representa una vivienda.

Variables principales: tipo de vivienda (PCV1), material de paredes (PCV2), techo (PCV3), condición (PCV4), piso (PCV5).

import geoquetzal as gq

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

`gq.emigracion()`

Registros de emigración internacional. 242,203 registros, 11 variables. Cada fila es una persona que emigró desde un hogar.

Variables principales: sexo (PEI3), edad al emigrar (PEI4), año de partida (PEI5).

import geoquetzal as gq

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

Datos Sub-Municipales

`gq.lugares_poblados()`

Indicadores pre-agregados a nivel de lugar poblado. 20,254 localidades, 200+ columnas. Cada fila representa un lugar poblado.

Los datos se derivan de las tres tablas censales (personas, hogares, viviendas) y se almacenan como conteos (no porcentajes). El denominador correcto depende del análisis a realizar.

Note

Los lugares poblados con códigos terminados en 999 (ej. 102999) representan asentamientos sin nombre oficial (“Otros Lugares Poblados”) y tienen coordenadas nulas. Se incluyen en los datos pero no pueden mapearse con geometría.

Parámetros:

Parámetro	Tipo	Descripción
`departamento`	`str \| int`	Filtra por departamento
`municipio`	`str \| int`	Filtra por municipio
`geometry`	`bool`	Si `True`, retorna GeoDataFrame con geometría de puntos (centroides)

import geoquetzal as gq

# Todos los lugares poblados
df = gq.lugares_poblados()

# Filtrar
df = gq.lugares_poblados(departamento="Sacatepéquez") #Carga todos los lugares poblados de Sacatepéquez
df = gq.lugares_poblados(municipio="Antigua Guatemala") #Carga todos los lugares poblados del municipio de Antigua Guatemala
df = gq.lugares_poblados(lugar_poblado=301001) #Carga los datos del lugar poblado 301001 (Antigua Guatemala), del municipio Antigua Guatemala, Sacatepéquez

# Como GeoDataFrame con puntos (centroides)
gdf = gq.lugares_poblados(geometry=True)

Columnas disponibles por tema:

Tema	Prefijo de columna	Fuente
Escalares (población, PEA, años de estudio)	`poblacion_total`, `pea_total`, `aneduca_promedio`…	persona
Autoidentificación étnica	`pcp12_maya`, `pcp12_ladino`…	persona
Comunidad lingüística maya	`pcp13_kiche`, `pcp13_mam`…	persona
Lengua materna	`pcp15_espanol`, `pcp15_kiche`…	persona
Discapacidad	`pcp16_a_sin_dificultad`…	persona
Escolaridad	`pcp17_a_ninguno`, `pcp17_a_primaria`…	persona
Alfabetismo	`pcp22_alfabeto`, `pcp22_no_alfabeto`	persona
Empleo	`pcp30_1d_agropecuarios`…	persona
Tipo de vivienda	`pcv1_casa_formal`, `pcv1_rancho`…	vivienda
Material de paredes	`pcv2_block`, `pcv2_adobe`…	vivienda
Material de piso	`pcv5_tierra`, `pcv5_torta_cemento`…	vivienda
Fuente de agua	`pch4_tuberia_dentro`, `pch4_rio`…	hogar
Saneamiento	`pch5_inodoro_red_drenajes`…	hogar
Electricidad	`pch8_red_electrica`, `pch8_candela`…	hogar
Equipamiento del hogar	`pch9_i_si` (internet), `pch9_m_si` (carro)…	hogar
Combustible para cocinar	`pch14_lena`, `pch14_gas_propano`…	hogar
Remesas	`pch15_si`, `pch15_no`	hogar
Emigración desde 2002	`pei1_si`, `pei1_no`	hogar

`gq.voronoi_lugares_poblados()`

Genera polígonos Voronoi aproximados como límites de lugares poblados, recortados a los límites municipales. Estos polígonos son aproximaciones para visualización coroplética — el INE no publica límites oficiales de lugares poblados.

Warning

Los lugares poblados con coordenadas nulas (códigos terminados en 999) son excluidos automáticamente. Los municipios con un solo lugar poblado retornan el polígono completo del municipio.

Parámetros:

Parámetro	Tipo	Descripción
`departamento`	`str \| int`	Filtra por departamento
`municipio`	`str \| int`	Filtra por municipio

import geoquetzal as gq

# Polígonos Voronoi para un municipio
vor = gq.voronoi_lugares_poblados(municipio="Antigua Guatemala")

# Para un departamento completo
vor = gq.voronoi_lugares_poblados(departamento="Sacatepéquez")

# Patrón típico: unir con datos censales para coropleta
lp  = gq.lugares_poblados(municipio="Antigua Guatemala")
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)

Funciones de Descripción

Todas las funciones de descripción retornan un DataFrame con todas las variables si no se especifica ninguna, o un dict con los detalles de la variable solicitada.

Función	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

# Listar todas las variables de un dataset
gq.describe_personas()
gq.describe_hogares()

# Detalle de una variable específica
gq.describe_personas("PCP12")
# {'variable': 'PCP12',
#  'etiqueta': 'Según su origen o historia, ¿cómo se considera o auto identifica?',
#  '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'}

Sistemas de Referencia de Coordenadas

from geoquetzal.crs import to_gtm, to_utm16n, suggest_crs

deptos = gq.departamentos()
suggest_crs(deptos)               # Muestra recomendaciones

deptos_gtm = to_gtm(deptos)       # Guatemala Transversa de Mercator (estándar nacional)
deptos_utm = to_utm16n(deptos)    # UTM Zona 16N (para cálculos de área y distancia)

CRS	Código	Uso recomendado
WGS 84	`EPSG:4326`	Default, mapas web
Guatemala TM (GTM)	`ESRI:103598`	Estándar nacional, mapas oficiales
UTM Zona 16N	`EPSG:32616`	Cálculos de área y distancia