> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tukanmx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Modelo de datos

> Cómo se relacionan las entidades geográficas, los indicadores, las observaciones, los polígonos y los lugares en Atlas.

Todo en Atlas gira alrededor de **entidades** y **lugares**:

* Las entidades son **polígonos** geográficos que tienen asociadas observaciones, como, por ejemplo, el valor observado o estimado de la población en esa entidad o polígono.
* Los **lugares** son establecimientos georreferenciados que se encuentran asociados a **marcas**, **empresas** y **giros**.

## Entidades geográficas

Una **entidad geográfica** es cualquier unidad territorial de México. Por el momento, Atlas maneja **9 niveles**, desde el polígono nacional hasta manzanas:

| `entity_type_id` | Qué es | Ejemplo de `entity_code` |
| - | - | - |
| `COUNTRY` | País | `MX` |
| `STATE` | Estado | `16` (Michoacán) |
| `MUNICIPALITY` | Municipio | `16053` (Morelia) |
| `ZIPCODE` | Código postal | `58000` |
| `LOCALITY` | Localidad | `160530001` |
| `NEIGHBORHOOD` | Asentamiento / colonia | `1605300010057` |
| `AGEB` | Área geoestadística básica | `1605300010293` |
| `URBAN_BLOCK` | Manzana urbana | `1605300010293008` |
| `RURAL_BLOCK` | Manzana rural | `0100101061763001` |

Las entidades están organizadas de forma jerárquica vía un `parent_code` que nos ayuda a asociar la relación entre municipios y estados, localidades y municipios, y así sucesivamente.

Así se ve una entidad completa, tal como la recibes al [consultar entidades](/es/atlas/catalogos/entidades):

| Atributo | Qué es | Ejemplo |
| - | - | - |
| `entity_id` | Identificador de la entidad. Es el que mandas al pedir observaciones | `1051` |
| `entity_code` | Código geográfico oficial. Es el que reconocerás de otras fuentes | `16053` |
| `entity_type_id` | Nivel geográfico al que pertenece | `MUNICIPALITY` |
| `name` | Nombre de la entidad | `Morelia` |
| `parent_code` | Código de la entidad que la contiene | `16` |
| `parent_name` | Nombre de esa entidad padre | `Michoacán de Ocampo` |

## Polígonos

Cada entidad geográfica que está dada de alta en la base de Atlas tiene un **polígono** que define la geometría oficial de su territorio.

Como los límites cambian con el tiempo, cada polígono está **versionado**: una misma entidad puede tener varias versiones y solo una de ellas es la vigente.

| Atributo | Qué es | Ejemplo |
| - | - | - |
| `polygon_code` | Código que identifica la versión: combina entidad y fecha de vigencia | `mex_municipality_16053_20250101` |
| `entity_type_id` | Nivel geográfico al que pertenece | `MUNICIPALITY` |
| `entity_code` | Código de la entidad que representa | `16053` |
| `valid_from` | Fecha desde la que esta versión es oficial | `2025-01-01` |
| `valid_to` | Fecha en que dejó de serlo. **`null` = versión vigente hoy** | `null` |
| `area_km2` | Superficie en kilómetros cuadrados | `1184.81` |
| `source_id` | Fuente cartográfica | `MEX_INEGI` |
| `bbox_west` | Longitud del borde oeste del rectángulo que encierra al polígono | `-101.5089` |
| `bbox_east` | Longitud del borde este | `-101.0426` |
| `bbox_south` | Latitud del borde sur | `19.4472` |
| `bbox_north` | Latitud del borde norte | `19.8623` |
| `centroid_lon` | Longitud del punto representativo del polígono | `-101.2791` |
| `centroid_lat` | Latitud del punto representativo | `19.6666` |

## Indicadores, colecciones y observaciones

Un **indicador** es una variable estadística a la cuál se le puede asignar una observación o estimación numérica. Por ejemplo: población total, porcentaje de viviendas de nivel socioeconómico alto, precio promedio de renta por metro cuadrado.

Atlas tiene más de **400 indicadores en su base de datos**, con los siguientes atributos:

| Atributo | Qué es | Ejemplo |
| - | - | - |
| `indicator_id` | Identificador numérico. Es el que mandas en las consultas | `1528` |
| `mnemonic` | Alias legible y estable del indicador | `census_population` |
| `name` | Nombre descriptivo | `Población total` |
| `description` | Qué mide exactamente y cómo se construye | `Población total censada.` |
| `unit_id` | Unidad en la que está expresado el valor | `PEOPLE` |
| `frequency_id` | Cada cuánto se actualiza | `DECENNIALY` |

Para facilitar la consulta de indicadores relacionados, las **[colecciones](/es/atlas/catalogos/colecciones)** agrupan indicadores por un tema en común y te permiten pedir todas las observaciones con una sola llamada en lugar de enumerar IDs o mnemónicos.

Finalmente, una **observación** es el valor de un indicador para una entidad en un periodo. Así es como la recibes al consultar [últimas observaciones](/es/atlas/estadisticas/ultimas-observaciones):

| Atributo | Qué es | Ejemplo |
| - | - | - |
| `value` | El valor observado o estimado | `849053.0` |
| `period` | Periodo al que corresponde el valor | `2020-01-01` |
| `entity_id` | Entidad a la que pertenece la observación | `1051` |
| `entity_code` | Código oficial de esa entidad | `16053` |
| `entity_name` | Nombre de la entidad | `Morelia` |
| `entity_type_id` | Nivel geográfico de la entidad | `MUNICIPALITY` |
| `indicator_id` | Indicador medido | `1528` |
| `indicator_name` | Nombre del indicador | `Población total` |
| `parent_code` | Código de la entidad que la contiene | `16` |
| `parent_name` | Nombre de esa entidad padre | `Michoacán de Ocampo` |
| `parent_entity_type_id` | Nivel geográfico de la entidad padre | `STATE` |
| `collection` | Colección de la que salió el indicador, si consultaste por colección | `null` |

Cada observación viene acompañada del contexto de su entidad y de su indicador, para que puedas interpretarla sin cruzarla contra los catálogos.

## Lugares

Un **lugar** es un establecimiento físico georreferenciado: una sucursal, una tienda, un cajero. Cada lugar pertenece a una **[marca](/es/atlas/catalogos/marcas)**, cada marca a una **[institución](/es/atlas/catalogos/instituciones)** —la empresa dueña de la marca, identificada por su RFC— y se clasifica con una o más **[categorías](/es/atlas/catalogos/categorias-de-lugares)** que describen su giro.

Estos son los datos que recibes al consultar lugares en el *endpoint* de [listado por entidad](/es/atlas/lugares/listado-por-entidad):

| Atributo | Qué es | Ejemplo |
| - | - | - |
| `id` | Identificador del lugar | `76504` |
| `brand_id` | Marca a la que pertenece | `2650` |
| `brand_name` | Nombre de la marca | `BanBajío` |
| `institution_id` | Institución dueña de la marca, en formato RFC | `BBA940707IE1.MX` |
| `institution_name` | Nombre de la institución | `Banco del Bajío` |
| `legal_name` | Razón social completa | `Banco del Bajío, S.A., Institución de Banca Múltiple` |
| `geography.latitude` | Latitud del establecimiento | `19.7023379` |
| `geography.longitude` | Longitud del establecimiento | `-101.2079899` |
| `geography.state` | Estado en el que se ubica | `Michoacán de Ocampo` |
| `categories` | Giros del establecimiento | `["Cajero automático", "Banco"]` |

Los lugares no se consultan uno por uno: los endpoints de [conteo por entidad](/es/atlas/lugares/conteo-por-entidad) los agregan por marca, institución o categoría dentro del área que tú definas — un radio, una dirección, una entidad geográfica o una [isócrona de traslado](/es/atlas/lugares/conteo-por-isocrona).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.