ENOE — Encuesta Nacional de Ocupación y Empleo¶

Acceso programático al dataset trimestral del INEGI sobre el mercado laboral mexicano (2005T1–2025T1): ~101.5 M microdatos en cinco tablas, 13 indicadores agregados nacionales y por entidad, distribuciones por sector económico y por posición en la ocupación.

→ Para uso narrado, ver Tutorial ENOE.

Namespace¶

datos_mexico.endpoints.enoe.EnoeNamespace ¶

EnoeNamespace(http: HttpClient)

Bases: BaseNamespace

Endpoints del dataset ENOE (Encuesta Nacional de Ocupación y Empleo).

La ENOE es la fuente oficial trimestral del INEGI sobre el mercado laboral mexicano. El observatorio expone tres familias de endpoints:

Catálogos y metadata (5): health, metadata, indicadores, entidades, etapas.
Indicadores agregados (5): series y snapshots nacionales y por entidad, ranking por indicador.
Distribuciones (4): ocupados por sector económico y por posición en la ocupación, snapshot y serie.
Microdatos (3): microdatos_schema, microdatos_count, microdatos_iter (sync generator) y microdatos_to_pandas (helper opcional que requiere pandas instalado).

Cobertura: 2005T1-2025T1 (80 trimestres, gap documental en 2020T2), nacional + 32 entidades federativas, ~101.5M microdatos en cinco tablas (viv, hog, sdem, coe1, coe2), 13 indicadores agregados y 76 mil agregados.

Examples:

Top 5 estados con mayor desempleo en el trimestre más reciente:

>>> from datos_mexico import DatosMexico
>>> with DatosMexico() as client:
...     r = client.enoe.ranking(
...         periodo="2025T1",
...         indicador="tasa_desocupacion",
...         limit=5,
...     )
...     for e in r.ranking:
...         print(f"{e.rank}. {e.entidad_nombre}: {e.valor:.2f}%")
1. Tabasco: 4.97%
2. Coahuila de Zaragoza: 3.56%
3. Durango: 3.46%
4. Ciudad de México: 3.45%
5. Tamaulipas: 3.37%

Notes

El observatorio mantiene un dominio operativo uniforme de 15 años o más en toda la serie (re-cálculo en la etapa clásica pre-2020T1 que originalmente publicaba 14+). El cambio de marco muestral en 2020T3 y la redefinición del TCCO en 2020T1 están documentados como caveats tipados (slug cambio_marco_2020T3, redefinicion_tcco_2020T1) en cada response que los toque.

health ¶

health() -> EnoeHealth

Estado del dataset ENOE: último periodo, conteos, cobertura.

Endpoint: GET /api/v1/enoe/health

metadata ¶

metadata() -> EnoeMetadata

Metadata completa del dataset: fuente, tablas y caveats.

Endpoint: GET /api/v1/enoe/metadata

indicadores ¶

indicadores() -> IndicadoresResponse

Catálogo de los 13 indicadores agregados disponibles.

Endpoint: GET /api/v1/enoe/catalogos/indicadores

Returns:

Type	Description
`IndicadoresResponse`	Response con `count` y la lista `indicadores` (slug, nombre,
`IndicadoresResponse`	unidad, fórmula, caveat aplicable).

entidades ¶

entidades() -> EntidadesResponse

Catálogo de las 32 entidades federativas con clave INEGI.

Endpoint: GET /api/v1/enoe/catalogos/entidades

etapas ¶

etapas() -> EtapasResponse

Catálogo de etapas metodológicas (clasica, etoe_telefonica, enoe_n).

Endpoint: GET /api/v1/enoe/catalogos/etapas-metodologicas

serie_nacional ¶

serie_nacional(
    *,
    indicador: str,
    desde: str | None = None,
    hasta: str | None = None,
    etapa: EtapaSlug | None = None,
) -> SerieNacionalResponse

Serie temporal nacional de un indicador.

Endpoint: GET /api/v1/enoe/indicadores/nacional/serie

Parameters:

Name	Type	Description	Default
`indicador`	`str`	Slug del indicador (ej. `"tasa_desocupacion"`, `"til1"`, `"tcco"`). Ver `indicadores()`.	required
`desde`	`str \| None`	Periodo inicial inclusivo en formato `YYYYTQ` (ej. `"2024T1"`).	`None`
`hasta`	`str \| None`	Periodo final inclusivo.	`None`
`etapa`	`EtapaSlug \| None`	Filtra por etapa metodológica. `None` (default) trae las tres etapas concatenadas.	`None`

Raises:

Type	Description
`NotFoundError`	Si el indicador no existe en el catálogo.

snapshot_nacional ¶

snapshot_nacional(
    *, periodo: str
) -> SnapshotNacionalResponse

Snapshot de los 13 indicadores nacionales en un periodo.

Endpoint: GET /api/v1/enoe/indicadores/nacional/snapshot

Parameters:

Name	Type	Description	Default
`periodo`	`str`	Trimestre en formato `YYYYTQ` (ej. `"2025T1"`).	required

serie_entidad ¶

serie_entidad(
    *,
    indicador: str,
    entidad_clave: str,
    desde: str | None = None,
    hasta: str | None = None,
    etapa: EtapaSlug | None = None,
) -> SerieEntidadResponse

Serie temporal por entidad federativa para un indicador.

Endpoint: GET /api/v1/enoe/indicadores/entidad/serie

Parameters:

Name	Type	Description	Default
`indicador`	`str`	Slug del indicador.	required
`entidad_clave`	`str`	Clave INEGI de 2 dígitos (ej. `"09"` = CDMX).	required
`desde`	`str \| None`	Periodo inicial inclusivo.	`None`
`hasta`	`str \| None`	Periodo final inclusivo.	`None`
`etapa`	`EtapaSlug \| None`	Filtra por etapa metodológica.	`None`

snapshot_entidad ¶

snapshot_entidad(
    *, periodo: str, indicador: str
) -> SnapshotEntidadResponse

Snapshot de un indicador para las 32 entidades en un periodo.

Endpoint: GET /api/v1/enoe/indicadores/entidad/snapshot

Parameters:

Name	Type	Description	Default
`periodo`	`str`	Trimestre `YYYYTQ`.	required
`indicador`	`str`	Slug del indicador.	required

ranking ¶

ranking(
    *,
    periodo: str,
    indicador: str,
    orden: OrdenRanking = "desc",
    limit: int = 5,
) -> RankingResponse

Ranking de entidades por un indicador en un periodo.

Endpoint: GET /api/v1/enoe/indicadores/entidad/ranking

Parameters:

Name	Type	Description	Default
`periodo`	`str`	Trimestre `YYYYTQ`.	required
`indicador`	`str`	Slug del indicador.	required
`orden`	`OrdenRanking`	`"desc"` (default, mayor a menor) o `"asc"`.	`'desc'`
`limit`	`int`	Cantidad de entidades a devolver (1..32).	`5`

distribucion_sectorial_snapshot ¶

distribucion_sectorial_snapshot(
    *,
    periodo: str,
    nivel: NivelGeografico = "nacional",
    entidad_clave: str | None = None,
) -> DistribucionSectorialSnapshot

Composición de ocupados por sector económico (12 sectores SCIAN).

Endpoint: GET /api/v1/enoe/ocupados/por-sector/snapshot

Parameters:

Name	Type	Description	Default
`periodo`	`str`	Trimestre `YYYYTQ`.	required
`nivel`	`NivelGeografico`	`"nacional"` o `"entidad"`.	`'nacional'`
`entidad_clave`	`str \| None`	Obligatorio si `nivel="entidad"`.	`None`

Raises:

Type	Description
`ValueError`	Si `nivel="entidad"` sin `entidad_clave`.

distribucion_sectorial_serie ¶

distribucion_sectorial_serie(
    *,
    sector_clave: str,
    nivel: NivelGeografico = "nacional",
    entidad_clave: str | None = None,
    desde: str | None = None,
    hasta: str | None = None,
) -> DistribucionSectorialSerie

Serie temporal de un sector económico.

Endpoint: GET /api/v1/enoe/ocupados/por-sector/serie

Parameters:

Name	Type	Description	Default
`sector_clave`	`str`	Clave del sector (ej. `"10"` = Servicios diversos).	required
`nivel`	`NivelGeografico`	`"nacional"` o `"entidad"`.	`'nacional'`
`entidad_clave`	`str \| None`	Obligatorio si `nivel="entidad"`.	`None`
`desde`	`str \| None`	Periodo inicial `YYYYTQ`.	`None`
`hasta`	`str \| None`	Periodo final `YYYYTQ`.	`None`

Raises:

Type	Description
`ValueError`	Si `nivel="entidad"` sin `entidad_clave`.

distribucion_posicion_snapshot ¶

distribucion_posicion_snapshot(
    *,
    periodo: str,
    nivel: NivelGeografico = "nacional",
    entidad_clave: str | None = None,
) -> DistribucionPosicionSnapshot

Composición de ocupados por posición en la ocupación (4 categorías).

Endpoint: GET /api/v1/enoe/ocupados/por-posicion/snapshot

Parameters:

Name	Type	Description	Default
`periodo`	`str`	Trimestre `YYYYTQ`.	required
`nivel`	`NivelGeografico`	`"nacional"` o `"entidad"`.	`'nacional'`
`entidad_clave`	`str \| None`	Obligatorio si `nivel="entidad"`.	`None`

distribucion_posicion_serie ¶

distribucion_posicion_serie(
    *,
    pos_clave: int,
    nivel: NivelGeografico = "nacional",
    entidad_clave: str | None = None,
    desde: str | None = None,
    hasta: str | None = None,
) -> DistribucionPosicionSerie

Serie temporal de una posición en la ocupación.

Endpoint: GET /api/v1/enoe/ocupados/por-posicion/serie

Parameters:

Name	Type	Description	Default
`pos_clave`	`int`	Clave de la posición (1=subordinados, 2=empleadores, 3=cuenta propia, 4=no remunerados).	required
`nivel`	`NivelGeografico`	`"nacional"` o `"entidad"`.	`'nacional'`
`entidad_clave`	`str \| None`	Obligatorio si `nivel="entidad"`.	`None`
`desde`	`str \| None`	Periodo inicial `YYYYTQ`.	`None`
`hasta`	`str \| None`	Periodo final `YYYYTQ`.	`None`

microdatos_schema ¶

microdatos_schema(
    tabla: TablaMicrodatos,
) -> MicrodatosSchema

Schema (columnas y descripciones) de una tabla de microdatos.

Endpoint: GET /api/v1/enoe/microdatos/{tabla}/schema

Parameters:

Name	Type	Description	Default
`tabla`	`TablaMicrodatos`	`"viv"`, `"hog"`, `"sdem"`, `"coe1"` o `"coe2"`.	required

microdatos_count ¶

microdatos_count(
    tabla: TablaMicrodatos,
    *,
    periodo: str,
    entidad_clave: str | None = None,
    sex: int | None = None,
    eda_min: int | None = None,
    eda_max: int | None = None,
) -> MicrodatosCount

Conteo de microdatos con filtros sin descargar las filas.

Endpoint: GET /api/v1/enoe/microdatos/{tabla}/count

Parameters:

Name	Type	Description	Default
`tabla`	`TablaMicrodatos`	`"viv"`, `"hog"`, `"sdem"`, `"coe1"` o `"coe2"`.	required
`periodo`	`str`	Trimestre `YYYYTQ` obligatorio.	required
`entidad_clave`	`str \| None`	Clave INEGI de 2 dígitos.	`None`
`sex`	`int \| None`	Sexo INEGI (`1`=hombre, `2`=mujer); aplica a sdem/coe1/coe2.	`None`
`eda_min`	`int \| None`	Edad mínima inclusiva; aplica a sdem/coe1/coe2.	`None`
`eda_max`	`int \| None`	Edad máxima inclusiva; aplica a sdem/coe1/coe2.	`None`

microdatos_page ¶

microdatos_page(
    tabla: TablaMicrodatos,
    *,
    periodo: str,
    page: int = 1,
    per_page: int = 1000,
    entidad_clave: str | None = None,
    sex: int | None = None,
    eda_min: int | None = None,
    eda_max: int | None = None,
    include_extras: bool = True,
) -> MicrodatosListResponse

Una página de microdatos con paginación explícita.

Endpoint: GET /api/v1/enoe/microdatos/{tabla}/list

Para iterar sobre todas las páginas en orden, usar :meth:microdatos_iter. Para volcar todo a un DataFrame, usar :meth:microdatos_to_pandas.

Parameters:

Name	Type	Description	Default
`tabla`	`TablaMicrodatos`	Tabla de microdatos.	required
`periodo`	`str`	Trimestre `YYYYTQ` obligatorio.	required
`page`	`int`	Número de página (1-indexed).	`1`
`per_page`	`int`	Filas por página (1..1000).	`1000`
`entidad_clave`	`str \| None`	Filtro opcional por entidad.	`None`
`sex`	`int \| None`	Filtro opcional por sexo.	`None`
`eda_min`	`int \| None`	Edad mínima.	`None`
`eda_max`	`int \| None`	Edad máxima.	`None`
`include_extras`	`bool`	Si `True` (default), incluye `extras_jsonb` con todas las variables originales no promovidas a columna.	`True`

microdatos_iter ¶

microdatos_iter(
    tabla: TablaMicrodatos,
    *,
    periodo: str,
    entidad_clave: str | None = None,
    sex: int | None = None,
    eda_min: int | None = None,
    eda_max: int | None = None,
    per_page: int = 1000,
    include_extras: bool = True,
    limit: int | None = None,
) -> Iterator[dict[str, Any]]

Iterador síncrono sobre microdatos paginados.

Hace requests pagina-a-pagina contra /api/v1/enoe/microdatos/{tabla}/list y produce un dict por fila. La iteración termina cuando la API marca has_next=False o cuando se alcanza limit (si se especifica).

Examples:

Iterar todos los microdatos sociodemográficos de CDMX en 2025T1:

>>> with DatosMexico() as client:
...     for row in client.enoe.microdatos_iter(
...         "sdem", periodo="2025T1", entidad_clave="09",
...     ):
...         # procesar row sin cargar todo a memoria
...         ...

Acotar a una muestra rápida (los primeros 100 registros):

>>> with DatosMexico() as client:
...     filas = list(
...         client.enoe.microdatos_iter(
...             "sdem", periodo="2025T1",
...             entidad_clave="09", limit=100,
...         )
...     )

Parameters:

Name	Type	Description	Default
`tabla`	`TablaMicrodatos`	Tabla de microdatos.	required
`periodo`	`str`	Trimestre `YYYYTQ` obligatorio.	required
`entidad_clave`	`str \| None`	Filtro opcional por entidad.	`None`
`sex`	`int \| None`	Filtro opcional por sexo (1=hombre, 2=mujer).	`None`
`eda_min`	`int \| None`	Edad mínima inclusiva.	`None`
`eda_max`	`int \| None`	Edad máxima inclusiva.	`None`
`per_page`	`int`	Filas por request (1..1000). Default 1000 minimiza el número de requests.	`1000`
`include_extras`	`bool`	Si `True` (default), incluye `extras_jsonb` con todas las variables ENOE no promovidas a columna. Activarlo por defecto sigue la convención de la Sub-fase 3.10b del observatorio: el SDK no oculta campos al investigador.	`True`
`limit`	`int \| None`	Máximo de filas a producir (atajo para muestras). `None` (default) itera hasta el final.	`None`

Yields:

Type	Description
`dict[str, Any]`	`dict` con los campos de cada fila, esquema dependiente de
`dict[str, Any]`	la tabla.

microdatos_to_pandas ¶

microdatos_to_pandas(
    tabla: TablaMicrodatos,
    *,
    periodo: str,
    entidad_clave: str | None = None,
    sex: int | None = None,
    eda_min: int | None = None,
    eda_max: int | None = None,
    per_page: int = 1000,
    include_extras: bool = True,
    limit: int | None = None,
) -> pd.DataFrame

Descarga microdatos a un pandas.DataFrame.

Construye internamente el iterador (:meth:microdatos_iter) y lo materializa en un único DataFrame. Para volúmenes grandes (>100k filas) considerar usar :meth:microdatos_iter y procesar por chunks.

Examples:

>>> with DatosMexico() as client:
...     df = client.enoe.microdatos_to_pandas(
...         "sdem", periodo="2025T1",
...         entidad_clave="09", limit=1000,
...     )
...     df["eda"].mean()
...     # 41.5

Parameters:

Name	Type	Description	Default
`tabla`	`TablaMicrodatos`	Tabla de microdatos.	required
`periodo`	`str`	Trimestre `YYYYTQ` obligatorio.	required
`entidad_clave`	`str \| None`	Filtro opcional por entidad.	`None`
`sex`	`int \| None`	Filtro opcional por sexo.	`None`
`eda_min`	`int \| None`	Edad mínima.	`None`
`eda_max`	`int \| None`	Edad máxima.	`None`
`per_page`	`int`	Filas por request.	`1000`
`include_extras`	`bool`	Si `True`, incluye `extras_jsonb`.	`True`
`limit`	`int \| None`	Máximo de filas a descargar.	`None`

Returns:

Type	Description
`DataFrame`	`pandas.DataFrame` con las filas. Si no hay matches devuelve
`DataFrame`	un DataFrame vacío.

Raises:

Type	Description
`ImportError`	Si `pandas` no está instalado. Instalar con `pip install datos-mexico[examples]` o `pip install pandas`.

Modelos¶

Modelos Pydantic para el dataset ENOE (Encuesta Nacional de Ocupación y Empleo).

Cobertura del observatorio ENOE: ~101.5M microdatos en cinco tablas (viv, hog, sdem, coe1, coe2) y ~76 mil indicadores agregados (nacionales y por entidad federativa), entre 2005T1 y 2025T1. Fuente: INEGI — ENOE 15+_.

.. _ENOE 15+: https://www.inegi.org.mx/programas/enoe/15ymas/

Convenciones (consistentes con CONSAR/ENIGH):

Indicadores numéricos (valores de tasas, conteos expandidos, participaciones) llegan como float o int desde la API. Los modelos los preservan como float/int puros: para los indicadores ENOE no se hace aritmética monetaria exacta, así que Decimal agregaría fricción sin beneficio. Los conteos expandidos (n_*, total_*) son int.
periodo es siempre str con formato YYYYTQ (ej. "2025T1").
entidad_clave es siempre str con dos dígitos (ej. "09" para CDMX); seguir el contrato canónico del observatorio post-Sub-fase 3.10c.
etapa es str | None con los slugs "clasica", "etoe_telefonica", o "enoe_n".
extra="allow" heredado del base config: si la API agrega campos nuevos, los modelos no rompen.

EnoeHealth ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/health.

EnoeTablaInfo ¶

Bases: DatosMexicoModel

Descripción de una tabla del dataset (microdatos o agregados).

CaveatMetodologico ¶

Bases: DatosMexicoModel

Caveat metodológico tipado.

Cada caveat documenta una salvedad publicada por el observatorio: cambio de marco muestral en 2020T3, redefinición del TCCO post-2020T1, re-cálculo del dominio 15+ en la etapa clásica, gap documental en 2020T2, etc.

EnoeMetadata ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/metadata.

IndicadorRef ¶

Bases: DatosMexicoModel

Item del catálogo de indicadores.

IndicadoresResponse ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/catalogos/indicadores.

EntidadRef ¶

Bases: DatosMexicoModel

Item del catálogo de entidades federativas.

EntidadesResponse ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/catalogos/entidades.

EtapaRef ¶

Bases: DatosMexicoModel

Item del catálogo de etapas metodológicas.

EtapasResponse ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/catalogos/etapas-metodologicas.

CoberturaTemporal ¶

Bases: DatosMexicoModel

Rango temporal cubierto por una respuesta de serie.

PuntoSerie ¶

Bases: DatosMexicoModel

Punto en una serie temporal de un indicador.

SerieNacionalResponse ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/indicadores/nacional/serie.

IndicadorSnapshotItem ¶

Bases: DatosMexicoModel

Un indicador dentro de un snapshot.

SnapshotNacionalResponse ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/indicadores/nacional/snapshot.

SerieEntidadResponse ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/indicadores/entidad/serie.

EntidadSnapshotRow ¶

Bases: DatosMexicoModel

Una entidad en un snapshot por indicador.

SnapshotEntidadResponse ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/indicadores/entidad/snapshot.

RankingEntidadRow ¶

Bases: DatosMexicoModel

Fila del ranking de entidades.

RankingResponse ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/indicadores/entidad/ranking.

DistribucionSectorialRow ¶

Bases: DatosMexicoModel

Fila de la distribución por sector económico.

DistribucionSectorialSnapshot ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/ocupados/por-sector/snapshot.

DistribucionSectorialSerie ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/ocupados/por-sector/serie.

DistribucionPosicionRow ¶

Bases: DatosMexicoModel

Fila de la distribución por posición en la ocupación.

DistribucionPosicionSnapshot ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/ocupados/por-posicion/snapshot.

DistribucionPosicionSerie ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/ocupados/por-posicion/serie.

MicrodatoColumna ¶

Bases: DatosMexicoModel

Una columna en el schema de una tabla de microdatos.

MicrodatosSchema ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/microdatos/{tabla}/schema.

MicrodatosCount ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/microdatos/{tabla}/count.

MicrodatosPagination ¶

Bases: DatosMexicoModel

Bloque de paginación del endpoint microdatos/list.

MicrodatosListResponse ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/enoe/microdatos/{tabla}/list.

data se preserva como list[dict] (sin tipar cada fila) porque cada tabla tiene un schema diferente y los nombres de columna son estables solo dentro de una tabla. Para análisis tipado, consultar el schema con :meth:EnoeNamespace.microdatos_schema y trabajar sobre el DataFrame de :meth:EnoeNamespace.microdatos_to_pandas.