Gabriel Gómez Gómez · 9 de junio, 2026

Cómo obtener las localidades y asentamientos humanos de Hidalgo usando datos de INEGI

Cuando empecé a trabajar con información territorial para Hidalgo, me encontré con una duda muy común: ¿una localidad es lo mismo que una colonia? La respuesta corta es no. Y entender esa diferencia es clave antes de construir cualquier catálogo para formularios, mapas, bases de datos o sistemas de consulta.
En este ejercicio armé un paquete en Python para obtener información de municipios, localidades y asentamientos humanos de Hidalgo, consumiendo datos del servicio de INEGI y generando archivos listos para usarse en proyectos web, bases de datos o análisis territorial.
Descargar ZIP del proyecto
Localidades y asentamientos humanos: no son lo mismo
Una localidad es una unidad geoestadística. Sirve para ubicar lugares habitados dentro de un municipio y suele tener información como clave, nombre, ámbito urbano/rural, periodo y, en los datos originales, coordenadas, altitud y población.
Un asentamiento humano, en cambio, es una subdivisión o referencia más específica dentro de una localidad.
Por ejemplo, en Pachuca de Soto la estructura correcta no sería simplemente “municipio → colonia”, sino algo más parecido a esto:

Hidalgo
└── Pachuca de Soto
    └── Localidad: Pachuca de Soto
        ├── Colonia Adolfo López Mateos
        ├── Colonia Aeropuerto
        ├── Fraccionamiento 15 de Septiembre
        └── Barrio / colonia / unidad habitacional...

Es decir, la jerarquía que conviene manejar es:

Entidad
└── Municipio
    └── Localidad
        └── Asentamiento humano

En el archivo trabajado, cada municipio contiene localidades, y cada localidad puede contener uno o varios asentamientos humanos. Esa estructura aparece reflejada en el JSON original que se usó como base.
Qué engloba una localidad
Una localidad agrupa un lugar habitado reconocido dentro de un municipio. Puede ser urbana o rural.
En términos prácticos, una localidad puede representar:
- Cabecera municipal
- Pueblo
- Ranchería
- Colonia rural reconocida como localidad
- Barrio rural
- Conjunto habitado
Por eso hay localidades que se llaman igual que la cabecera municipal, por ejemplo:
- Municipio: Pachuca de Soto
- Localidad: Pachuca de Soto
Pero también puede haber otras localidades dentro del mismo municipio, como barrios, comunidades o zonas rurales.
En el JSON limpio que generé, cada localidad conserva estos campos:

{
  "claveGeoestadistica": "130480001",
  "claveLocalidad": "0001",
  "nombre": "Pachuca de Soto",
  "ambito": "URBANO",
  "periodo": "2015-06-01",
  "tipo": "localidad",
  "asentamientosHumanos": []
}

Quité de este nivel los campos:
campos-removidosTXT
```
latitud
longitud
altitud
pob_total
```
porque para el uso final era mejor concentrar la población a nivel municipal y evitar confundir datos de localidad con datos de asentamiento humano.
Qué engloba un asentamiento humano
Un asentamiento humano es el nivel donde normalmente aparecen lo que muchas personas llaman “colonias”.
Pero no todo asentamiento humano es colonia. También puede ser:
- Barrio
- Fraccionamiento
- Unidad habitacional
- Ejido
- Pueblo
- Ranchería
- Residencial
- Ampliación
Cómo obtener la información
Para obtener la información usé el servicio de INEGI con tres niveles principales:

Municipios
Localidades
Asentamientos humanos

La lógica del programa es la siguiente:

1. Descargar todos los municipios de Hidalgo.
2. Recorrer municipio por municipio.
3. Descargar sus localidades.
4. Descargar sus asentamientos humanos.
5. Relacionar asentamientos humanos con localidades.
6. Generar CSV, JSON y GeoJSON.

La clave de Hidalgo es: 13
Entonces, a nivel de lógica, el programa trabaja con estas rutas:

Municipios de Hidalgo:
https://gaia.inegi.org.mx/wscatgeo/v2/mgem/13

Localidades por municipio:
https://gaia.inegi.org.mx/wscatgeo/v2/localidades/13/{claveMunicipio}

Asentamientos humanos por municipio:
https://gaia.inegi.org.mx/wscatgeo/v2/asentamientos/13/{claveMunicipio}

Por ejemplo, para Pachuca de Soto, cuya clave municipal es 048, se consultan:

Localidades:
https://gaia.inegi.org.mx/wscatgeo/v2/localidades/13/048

Asentamientos humanos:
https://gaia.inegi.org.mx/wscatgeo/v2/asentamientos/13/048

Cómo funciona el programa
El paquete tiene una estructura sencilla:

inegi_hidalgo_catalogo_actualizado/
├── data/
│   ├── raw/
│   ├── dcah/
│   └── output/
├── docs/
├── scripts/
│   ├── generar_catalogo_hidalgo.py
│   ├── generar_geojson_enriquecido.py
│   ├── run_all.py
│   └── utils_inegi.py
├── requirements.txt
├── requirements-geo.txt
└── README.md

El archivo principal para ejecutar todo es:
terminalBASH
```
python scripts/run_all.py
```
Este comando primero genera el catálogo tabular y después genera el GeoJSON preliminar.
Instalación
Primero descomprimo el ZIP y entro a la carpeta:
terminalBASH
```
cd inegi_hidalgo_catalogo_actualizado
```
Creo un entorno virtual:
terminalBASH
```
python -m venv .venv
```
Lo activo en Linux o macOS:
terminalBASH
```
source .venv/bin/activate
```
En Windows PowerShell:
PowerShellPOWERSHELL
```
.\.venv\Scripts\Activate.ps1
```
Instalo las dependencias base:
terminalBASH
```
pip install -r requirements.txt
```
Y ejecuto todo:
terminalBASH
```
python scripts/run_all.py
```
Qué archivos se obtienen
Al ejecutar el programa se generan los archivos dentro de:
outputTXT
```
data/output/
```
Los archivos principales son:

hidalgo_localidades.csv
hidalgo_asentamientos_humanos.csv
hidalgo_asentamientos_humanos_localidades.csv
hidalgo_asentamientos_humanos_localidades.json
hidalgo_asentamientos_humanos_enriquecido.geojson
hidalgo_asentamientos_humanos_enriquecido_puntos.geojson

1. hidalgo_localidades.csv
Este archivo contiene las localidades de Hidalgo por municipio. Sirve si necesito revisar solamente el nivel de localidad.
Incluye campos como:

cve_ent
nom_ent
cve_mun
nom_mun
cve_loc
nom_loc
ambito
latitud
longitud
altitud
pob_total
periodo
cvegeo_loc

Este archivo conserva los campos completos de localidad porque es el CSV técnico base.
2. hidalgo_asentamientos_humanos.csv
Este archivo contiene los asentamientos humanos por municipio y localidad.
Sirve si necesito trabajar directamente con colonias, barrios, fraccionamientos, rancherías, pueblos, ejidos y demás tipos de asentamiento.
Incluye campos como:

cve_ent
nom_ent
cve_mun
nom_mun
cve_loc
nom_loc
cve_asen
nom_asen
tipo_asen
periodo
cvegeo_loc
cvegeo_asen

También conserva algunos campos heredados de localidad para facilitar cruces técnicos.
3. hidalgo_asentamientos_humanos_localidades.csv
Este fue el archivo que faltaba y lo agregué al paquete. Es un CSV combinado, pensado para usarlo en Excel, bases de datos o importaciones rápidas.
Tiene una estructura plana:

estado
claveEntidad
municipio
claveMunicipio
claveGeoestadisticaMunicipio
localidad
claveLocalidad
claveGeoestadisticaLocalidad
ambito
periodoLocalidad
asentamientoHumano
claveAsentamiento
tipoAsentamiento
periodoAsentamiento
claveGeoestadisticaAsentamiento
tipoRegistro

La regla es:

Si una localidad tiene asentamientos humanos:
    genera una fila por cada asentamiento.

Si una localidad no tiene asentamientos humanos:
    genera una fila con tipoRegistro = localidad_sin_asentamiento.

Este archivo no incluye:
campos-excluidosTXT
```
latitud
longitud
altitud
pob_total
```
porque la intención fue dejar la información limpia para consulta administrativa y no mezclar población o coordenadas a nivel incorrecto.
4. hidalgo_asentamientos_humanos_localidades.json
Este es el archivo más útil para frontend, APIs o selects dependientes.
Tiene esta estructura:

{
  "estado": "Hidalgo",
  "claveEntidad": "13",
  "claveGeoestadistica": "13",
  "tipo": "catalogo_asentamientos_humanos_localidades",
  "municipios": [
    {
      "municipio": "Pachuca de Soto",
      "claveMunicipio": "048",
      "claveGeoestadistica": "13048",
      "localidades": [
        {
          "claveGeoestadistica": "130480001",
          "claveLocalidad": "0001",
          "nombre": "Pachuca de Soto",
          "ambito": "URBANO",
          "periodo": "2015-06-01",
          "tipo": "localidad",
          "asentamientosHumanos": [
            {
              "claveAsentamiento": "0152",
              "nombre": "ADOLFO LÓPEZ MATEOS",
              "tipoAsentamiento": "COLONIA",
              "periodo": "11/2024",
              "claveGeoestadistica": "1304800010152",
              "claveLocalidad": "0001",
              "claveGeoestadisticaLocalidad": "130480001",
              "localidad": "Pachuca de Soto",
              "tipo": "asentamiento"
            }
          ]
        }
      ],
      "resumen": {
        "total": 35,
        "localidades": 35,
        "asentamientos": 430,
        "urbanas": 3,
        "rurales": 32,
        "poblacionTotal": 314313
      }
    }
  ]
}

Este JSON permite hacer una interfaz como:

Selecciona municipio
→ Selecciona localidad
→ Selecciona asentamiento humano

5. hidalgo_asentamientos_humanos_enriquecido.geojson
Este archivo sirve para mapas. Por defecto, si no se usa una capa DCAH, el programa genera puntos preliminares usando la coordenada de la localidad asociada.
Eso quiere decir que el punto no representa la geometría exacta de la colonia o asentamiento humano, sino una referencia espacial aproximada.
Para generar el GeoJSON básico:

python scripts/generar_geojson_enriquecido.py --geometry punto

Cómo generar polígonos reales de asentamientos humanos
Para tener geometría real de colonias o asentamientos, se necesita la capa DCAH de INEGI.
En ese caso, el paquete incluye este comando:

python scripts/generar_geojson_enriquecido.py --dcah /ruta/a/DCAH.shp --geometry poligono

Esto genera:

hidalgo_asentamientos_humanos_enriquecido_poligonos.geojson
hidalgo_asentamientos_humanos_enriquecido.geojson

Si quiero generar puntos y polígonos al mismo tiempo:

python scripts/generar_geojson_enriquecido.py --dcah /ruta/a/DCAH.shp --geometry both

Y se obtienen:

hidalgo_asentamientos_humanos_enriquecido_puntos.geojson
hidalgo_asentamientos_humanos_enriquecido_poligonos.geojson
hidalgo_asentamientos_humanos_enriquecido.geojson

Conclusión
Este proceso me permitió ordenar correctamente la información territorial de Hidalgo usando datos de INEGI. La parte más importante fue entender que localidad y asentamiento humano no son lo mismo.
La localidad sirve como unidad geoestadística base. El asentamiento humano representa un nivel más específico, donde aparecen colonias, barrios, fraccionamientos, rancherías, pueblos, ejidos y otras formas de ocupación territorial.
Para explicarlo de forma sencilla, utilicé una analogía parecida a una dirección: no se llega directamente a una colonia sin antes ubicar el estado, el municipio y la localidad. De la misma manera, en los datos de INEGI, un asentamiento humano está asociado a una localidad mediante la clave cve_loc. Esto permite organizar la información de forma jerárquica y entender que colonias, barrios, fraccionamientos o rancherías forman parte de una localidad específica dentro de un municipio.
El paquete final permite generar archivos CSV, JSON y GeoJSON, y deja lista la información para integrarse en un sistema web, una base de datos o un mapa interactivo.
La mayor ventaja es que el catálogo respeta la jerarquía correcta:

Estado → Municipio → Localidad → Asentamiento humano

Y evita un error común: tratar todas las colonias como si fueran localidades o asignar población de localidad directamente a una colonia.
Descargar ZIP del proyecto

Cómo obtener las localidades y asentamientos humanos de Hidalgo usando datos de INEGI

Localidades y asentamientos humanos: no son lo mismo

Qué engloba una localidad

Qué engloba un asentamiento humano

Cómo obtener la información

Cómo funciona el programa

Instalación

Qué archivos se obtienen

1. `hidalgo_localidades.csv`

2. `hidalgo_asentamientos_humanos.csv`

3. `hidalgo_asentamientos_humanos_localidades.csv`

4. `hidalgo_asentamientos_humanos_localidades.json`

5. `hidalgo_asentamientos_humanos_enriquecido.geojson`

Cómo generar polígonos reales de asentamientos humanos

Conclusión

Cómo obtener las localidades y asentamientos humanos de Hidalgo usando datos de INEGI

Localidades y asentamientos humanos: no son lo mismo

Qué engloba una localidad

Qué engloba un asentamiento humano

Cómo obtener la información

Cómo funciona el programa

Instalación

Qué archivos se obtienen

1. hidalgo_localidades.csv

2. hidalgo_asentamientos_humanos.csv

3. hidalgo_asentamientos_humanos_localidades.csv

4. hidalgo_asentamientos_humanos_localidades.json

5. hidalgo_asentamientos_humanos_enriquecido.geojson

Cómo generar polígonos reales de asentamientos humanos

Conclusión

1. `hidalgo_localidades.csv`

2. `hidalgo_asentamientos_humanos.csv`

3. `hidalgo_asentamientos_humanos_localidades.csv`

4. `hidalgo_asentamientos_humanos_localidades.json`

5. `hidalgo_asentamientos_humanos_enriquecido.geojson`