CDMX servidores públicos¶

Acceso al padrón del Poder Ejecutivo del Gobierno de la Ciudad de México.

→ Para uso narrado, ver Tutorial CDMX.

Namespace¶

datos_mexico.endpoints.cdmx.CdmxNamespace ¶

CdmxNamespace(http: HttpClient)

Bases: BaseNamespace

Endpoints del dataset Servidores Públicos CDMX.

Acceso al padrón de personal del Poder Ejecutivo del Gobierno de la Ciudad de México. La API expone tres familias de endpoints:

Dashboard / Stats: KPIs preagregados (dashboard_stats, servidores_stats).
Sectores: lista, detalle, comparación, ranking (sectores, sector_stats, sectores_compare, sectores_ranking).
Servidores: lista paginada con filtros (servidores_lista).
Catálogos: listas de referencia para construir filtros (catalogo_*).

Examples:

>>> from datos_mexico import DatosMexico
>>> with DatosMexico() as client:
...     stats = client.cdmx.dashboard_stats()
...     print(f"{stats.total_servidores:,} servidores")
246,831 servidores

dashboard_stats ¶

dashboard_stats() -> DashboardStats

KPIs preagregados del padrón de servidores públicos CDMX.

Devuelve los KPIs principales más seis distribuciones precomputadas (sueldo, edad, contratación, personalidad jurídica, antigüedad, ranking de sectores) en una sola llamada. Pensado para alimentar un dashboard sin requerir cálculos del lado del cliente.

Endpoint: GET /api/v1/dashboard/stats

servidores_stats ¶

servidores_stats(
    *,
    sector_id: int | None = None,
    sexo: str | None = None,
    edad_min: int | None = None,
    edad_max: int | None = None,
    sueldo_min: float | None = None,
    sueldo_max: float | None = None,
    puesto_search: str | None = None,
    tipo_contratacion_id: int | None = None,
    tipo_personal_id: int | None = None,
    universo_id: int | None = None,
) -> ServidoresStats

Stats agregados con filtros opcionales sobre el padrón.

Aplica los filtros como query string y la API devuelve estadísticos de ese subconjunto. Todos los filtros son opcionales: sin filtros equivale al padrón completo.

Endpoint: GET /api/v1/servidores/stats

Parameters:

Name	Type	Description	Default
`sector_id`	`int \| None`	ID del sector. Ver `catalogo_sectores()`.	`None`
`sexo`	`str \| None`	`"FEMENINO"`, `"MASCULINO"` o `"NA"`.	`None`
`edad_min`	`int \| None`	Edad mínima inclusiva.	`None`
`edad_max`	`int \| None`	Edad máxima inclusiva.	`None`
`sueldo_min`	`float \| None`	Sueldo bruto mínimo en MXN.	`None`
`sueldo_max`	`float \| None`	Sueldo bruto máximo en MXN.	`None`
`puesto_search`	`str \| None`	Texto a buscar en el nombre del puesto.	`None`
`tipo_contratacion_id`	`int \| None`	ID de tipo de contratación.	`None`
`tipo_personal_id`	`int \| None`	ID de tipo de personal.	`None`
`universo_id`	`int \| None`	ID de universo presupuestal.	`None`

sectores ¶

sectores() -> list[Sector]

Lista de sectores del Gobierno de la CDMX con resumen.

Endpoint: GET /api/v1/sectores/

Notes

Puede incluir sectores de prueba con total_servidores == 0; sus campos numéricos vendrán como None. Filtrar con [s for s in sectores if s.total_servidores > 0] si se desea sólo sectores con personal asignado.

sector_stats ¶

sector_stats(sector_id: int) -> SectorStats

Detalle estadístico de un sector específico, incluye top puestos.

Endpoint: GET /api/v1/sectores/{sector_id}/stats

Raises:

Type	Description
`NotFoundError`	Si no existe un sector con ese ID.

sectores_compare ¶

sectores_compare(a: int, b: int) -> SectoresComparison

Comparación lado a lado de dos sectores.

Endpoint: GET /api/v1/sectores/compare?a=..&b=..

Parameters:

Name	Type	Description	Default
`a`	`int`	ID del primer sector.	required
`b`	`int`	ID del segundo sector.	required

sectores_ranking ¶

sectores_ranking() -> list[SectorRanking]

Ranking de sectores ordenados por sueldo promedio descendente.

Endpoint: GET /api/v1/analytics/sectores/ranking

puestos_ranking ¶

puestos_ranking(*, limit: int = 20) -> list[PuestoRanking]

Top puestos por sueldo promedio descendente.

Endpoint: GET /api/v1/analytics/puestos/ranking

Parameters:

Name	Type	Description	Default
`limit`	`int`	Cantidad de puestos a devolver.	`20`

brecha_edad ¶

brecha_edad() -> list[BrechaEdadRow]

Brecha salarial de género por bucket de edad.

Endpoint: GET /api/v1/analytics/brecha-edad

servidores_lista ¶

servidores_lista(
    *,
    page: int = 1,
    per_page: int = 50,
    order_by: str | None = None,
    order: str | None = None,
    sector_id: int | None = None,
    sexo: str | None = None,
    edad_min: int | None = None,
    edad_max: int | None = None,
    sueldo_min: float | None = None,
    sueldo_max: float | None = None,
    puesto_search: str | None = None,
    tipo_contratacion_id: int | None = None,
    tipo_personal_id: int | None = None,
    universo_id: int | None = None,
) -> PaginatedResponse[Servidor]

Lista paginada de servidores con filtros.

Endpoint: GET /api/v1/servidores/

Parameters:

Name	Type	Description	Default
`page`	`int`	Número de página (1-indexed).	`1`
`per_page`	`int`	Elementos por página.	`50`
`order_by`	`str \| None`	Campo para ordenar (ej. `"sueldo_bruto"`).	`None`
`order`	`str \| None`	`"asc"` o `"desc"`.	`None`
`sector_id`	`int \| None`	ID del sector.	`None`
`sexo`	`str \| None`	`"FEMENINO"`, `"MASCULINO"` o `"NA"`.	`None`
`edad_min`	`int \| None`	Edad mínima.	`None`
`edad_max`	`int \| None`	Edad máxima.	`None`
`sueldo_min`	`float \| None`	Sueldo bruto mínimo.	`None`
`sueldo_max`	`float \| None`	Sueldo bruto máximo.	`None`
`puesto_search`	`str \| None`	Texto a buscar en el puesto.	`None`
`tipo_contratacion_id`	`int \| None`	ID de tipo de contratación.	`None`
`tipo_personal_id`	`int \| None`	ID de tipo de personal.	`None`
`universo_id`	`int \| None`	ID de universo presupuestal.	`None`

servidor_detail ¶

servidor_detail(servidor_id: int) -> ServidorDetail

Detalle completo de un servidor por ID.

Devuelve campos derivados ya resueltos (tipo_contratacion, tipo_personal, tipo_nomina, universo, fecha_ingreso) que la vista de listado servidores_lista() no incluye.

Endpoint: GET /api/v1/servidores/{servidor_id}

Raises:

Type	Description
`NotFoundError`	Si no existe un servidor con ese ID.

catalogo_sectores ¶

catalogo_sectores() -> list[CatalogItem]

Catálogo de sectores con conteo de servidores. Útil para dropdowns.

Endpoint: GET /api/v1/catalogos/sectores

catalogo_puestos ¶

catalogo_puestos(*, limit: int = 100) -> list[CatalogItem]

Catálogo de puestos con conteo de servidores.

Endpoint: GET /api/v1/catalogos/puestos

Parameters:

Name	Type	Description	Default
`limit`	`int`	Cantidad máxima de puestos a devolver.	`100`

catalogo_sexos ¶

catalogo_sexos() -> list[CatalogItem]

Catálogo de sexos disponibles en el padrón.

Endpoint: GET /api/v1/catalogos/sexos

catalogo_tipos_contratacion ¶

catalogo_tipos_contratacion() -> list[CatalogItem]

Catálogo de tipos de contratación (BASE, HONORARIOS, ...).

Endpoint: GET /api/v1/catalogos/tipos-contratacion

catalogo_tipos_personal ¶

catalogo_tipos_personal() -> list[CatalogItem]

Catálogo de tipos de personal (CONFIANZA, SINDICALIZADO, ...).

Endpoint: GET /api/v1/catalogos/tipos-personal

catalogo_tipos_nomina ¶

catalogo_tipos_nomina() -> list[CatalogItem]

Catálogo de tipos de nómina.

Endpoint: GET /api/v1/catalogos/tipos-nomina

catalogo_niveles_salariales ¶

catalogo_niveles_salariales() -> list[CatalogItem]

Catálogo de niveles salariales.

Endpoint: GET /api/v1/catalogos/niveles-salariales

catalogo_universos ¶

catalogo_universos() -> list[CatalogItem]

Catálogo de universos presupuestales.

Endpoint: GET /api/v1/catalogos/universos

Modelos¶

Modelos Pydantic para el dataset Servidores Públicos de la CDMX.

Cada modelo documenta el endpoint de origen. La API mezcla convenciones de nombres entre endpoints: los endpoints de tipo "dashboard" usan camelCase (totalServidores, avgSalary); los demás usan snake_case (total_servidores, sueldo_bruto_avg). Los modelos exponen siempre snake_case en Python; los aliases vía Field(alias=...) aceptan camelCase desde la API.

MoneyStr `module-attribute` ¶

MoneyStr = Annotated[Decimal, BeforeValidator(_to_decimal)]

Decimal proveniente de un string monetario ("14915.00").

DistributionItem ¶

Bases: DatosMexicoModel

Bucket genérico {"label": str, "count": int}.

Reusado por salary_distribution, age_distribution, contract_types, personal_types y seniority_distribution del dashboard.

LabeledAvg ¶

Bases: DatosMexicoModel

Bucket {"label": str, "avg": float}. Usado en salary_by_age.

LabeledAvgCount ¶

Bases: DatosMexicoModel

Bucket {"label", "avg", "count"}. Usado en salary_by_seniority.

BrutoNetoBucket ¶

Bases: DatosMexicoModel

Item de brutoNetoByRange del dashboard.

SectorAggregate ¶

Bases: DatosMexicoModel

Sector dentro del dashboard (top15Sectors y allSectors).

GenderGapSectorRow ¶

Bases: DatosMexicoModel

Item de genderGapBySector del dashboard.

TopPosition ¶

Bases: DatosMexicoModel

Item de topPositions del dashboard.

DashboardStats ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/dashboard/stats.

KPIs preagregados del padrón completo de la CDMX más seis distribuciones listas para graficar.

DistribucionSueldoBucket ¶

Bases: DatosMexicoModel

Bucket de servidores/stats. Usa rango en vez de label.

ServidoresStats ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/servidores/stats (con filtros opcionales).

Cuando los filtros aplicados producen 0 registros, los campos numéricos agregados (sueldo_*, edad_avg, brecha_genero_pct) llegan como null.

Sector ¶

Bases: DatosMexicoModel

Item de GET /api/v1/sectores/ (lista de sectores con resumen).

Para sectores con total_servidores == 0 (típicamente sectores de prueba o recién creados sin personal asignado), sueldo_bruto_avg llega como null.

TopPuesto ¶

Bases: DatosMexicoModel

Top puesto dentro de un sector, devuelto por sectores/{id}/stats.

SectorStats ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/sectores/{sector_id}/stats.

Para sectores con total_servidores == 0 los campos agregados numéricos llegan como null y top_puestos queda como lista vacía.

SectoresComparison ¶

Bases: DatosMexicoModel

Respuesta de GET /api/v1/sectores/compare?a=..&b=...

SectorRanking ¶

Bases: DatosMexicoModel

Item de GET /api/v1/analytics/sectores/ranking.

PuestoRanking ¶

Bases: DatosMexicoModel

Item de GET /api/v1/analytics/puestos/ranking.

El campo gap_vs_next es None para el último elemento del ranking o cuando la API no puede calcular un delta.

BrechaEdadRow ¶

Bases: DatosMexicoModel

Item de GET /api/v1/analytics/brecha-edad.

Servidor ¶

Bases: DatosMexicoModel

Item de GET /api/v1/servidores/ (vista resumida).

Los campos monetarios (sueldo_bruto, sueldo_neto) llegan como string desde la API y se convierten a Decimal para preservar precisión. El apellido_2 puede no estar presente para personas con un solo apellido.

ServidorDetail ¶

Bases: DatosMexicoModel

Detalle completo devuelto por GET /api/v1/servidores/{servidor_id}.

A diferencia de Servidor (vista de listado), incluye los campos derivados de nombramientos y catalogos ya resueltos por nombre: tipo_contratacion, tipo_personal, tipo_nomina, universo y fecha_ingreso. Cualquier campo puede llegar como None cuando el dato fuente venía sin esa información.

CatalogItem ¶

Bases: DatosMexicoModel

Item común de cualquier endpoint /api/v1/catalogos/*.

CDMX servidores públicos¶

Namespace¶

datos_mexico.endpoints.cdmx.CdmxNamespace ¶

dashboard_stats ¶

servidores_stats ¶

sectores ¶

sector_stats ¶

sectores_compare ¶

sectores_ranking ¶

puestos_ranking ¶

brecha_edad ¶

servidores_lista ¶

servidor_detail ¶

catalogo_sectores ¶

catalogo_puestos ¶

catalogo_sexos ¶

catalogo_tipos_contratacion ¶

catalogo_tipos_personal ¶

catalogo_tipos_nomina ¶

catalogo_niveles_salariales ¶

catalogo_universos ¶

Modelos¶

MoneyStr module-attribute ¶

DistributionItem ¶

LabeledAvg ¶

LabeledAvgCount ¶

BrutoNetoBucket ¶

SectorAggregate ¶

GenderGapSectorRow ¶

TopPosition ¶

DashboardStats ¶

DistribucionSueldoBucket ¶

ServidoresStats ¶

Sector ¶

TopPuesto ¶

SectorStats ¶

SectoresComparison ¶

SectorRanking ¶

PuestoRanking ¶

BrechaEdadRow ¶

Servidor ¶

ServidorDetail ¶

CatalogItem ¶

MoneyStr `module-attribute` ¶