> ## 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.

# Últimas observaciones

> Obtén el valor más reciente de cualquier indicador para las entidades geográficas que elijas.

Este es el endpoint central de Atlas. Regresa la **observación más reciente** de cada indicador para cada entidad geográfica que pidas.

El resultado es una fila por combinación de entidad x indicador, con el valor, el periodo al que corresponde y el contexto de la entidad (nombre, tipo, entidad padre).

Hay dos formas de hacer las consultas.

* Por su `indicator_id`. Encuentra los IDs en el [catálogo de indicadores](/es/atlas/catalogos/indicadores).
* Por el `collection_id`. Trae los resultados de todos los indicadores dentro de la colección. Puedes consultar el catálogo de las colecciones en [colecciones](/es/atlas/catalogos/colecciones).

Adicionalmente es necesario especificar para qué entidad geográfica se requiere la información.

* `geo_entity_ids` recibe una lista explícita de `entity_id`.
* `geo_filter` recibe todo un nivel geográfico dentro de una entidad padre, por ejemplo *"todas las AGEBs de Michoacán"* o *"todos los códigos postales de Morelia"*.

<Warning>
  **Manda siempre un filtro geográfico.**
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://client.tukanmx.com/tukan-atlas/latest/" \
    -H "Authorization: Token $API_TUKAN" \
    -H "Content-Type: application/json" \
    -d '{
      "indicator_ids": [1528],
      "geo_filter": {
        "entity_type_id": "MUNICIPALITY",
        "within": {"entity_code": "16", "entity_type_id": "STATE"}
      }
    }'
  ```

  ```python Python theme={null}
  import os
  import requests

  headers = {"Authorization": f"Token {os.environ['API_TUKAN']}"}

  # Población total (1528) de todos los municipios de Michoacán (16)
  resp = requests.post(
      "https://client.tukanmx.com/tukan-atlas/latest/",
      headers=headers,
      json={
          "indicator_ids": [1528],
          "geo_filter": {
              "entity_type_id": "MUNICIPALITY",
              "within": {"entity_code": "16", "entity_type_id": "STATE"},
          },
      },
  )
  resp.raise_for_status()
  for obs in resp.json()["results"][:3]:
      print(obs["entity_name"], obs["value"], obs["period"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "count": 113,
    "results": [
      {
        "entity_id": "1000",
        "entity_code": "16085",
        "entity_name": "Tangancícuaro",
        "entity_type_id": "MUNICIPALITY",
        "indicator_id": "1528",
        "indicator_name": "Población total",
        "indicator_name_en": "Total population",
        "value": 35256.0,
        "period": "2020-01-01",
        "parent_code": "16",
        "parent_name": "Michoacán de Ocampo",
        "parent_name_en": "Michoacán de Ocampo",
        "parent_entity_type_id": "STATE",
        "collection": null
      }
    ]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml es/atlas/openapi-atlas.json POST /latest/
openapi: 3.0.3
info:
  title: Atlas API
  description: >-
    API para consultar indicadores geoespaciales, catálogos geográficos y
    densidad de lugares en México.
  version: 1.0.0
  contact:
    name: Soporte Tukan
    email: contacto@tukanmx.com
servers:
  - url: https://client.tukanmx.com/tukan-atlas
    description: Servidor de producción
security:
  - tokenAuth: []
paths:
  /latest/:
    post:
      summary: Últimas observaciones
      description: >-
        Regresa la observación mas reciente por entidad geográfica para una
        lista de indicadores o colecciones. Filtra por entidades específicas con
        geo_entity_ids, o por jerarquía geográfica con geo_filter. No se pueden
        usar ambos a la vez.
      operationId: getLatestObservations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LatestRequest'
      responses:
        '200':
          description: Observaciones obtenidas exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatestResponse'
        '400':
          description: Solicitud inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Token de autenticación inválido o ausente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    LatestRequest:
      type: object
      description: >-
        Al menos uno de indicator_ids o collection_ids es requerido. No se
        pueden combinar geo_entity_ids y geo_filter.
      properties:
        indicator_ids:
          type: array
          items:
            type: integer
          maxItems: 20
          description: >-
            Lista de IDs de indicadores (máximo 20). Requerido si no se
            proporciona collection_ids.
          example:
            - 1528
        collection_ids:
          type: array
          items:
            type: integer
          maxItems: 5
          description: >-
            Lista de IDs de colecciones (máximo 5). Requerido si no se
            proporciona indicator_ids.
          example:
            - 501
        geo_entity_ids:
          type: array
          items:
            type: integer
          description: >-
            Filtrar por IDs de entidades geográficas. No combinar con
            geo_filter.
          example:
            - 1051
        geo_filter:
          $ref: '#/components/schemas/LatestGeoFilter'
    LatestResponse:
      type: object
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/LatestObservationItem'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
    LatestGeoFilter:
      type: object
      description: >-
        Filtro geográfico jerárquico. Devuelve todas las entidades del tipo
        indicado contenidas dentro de la entidad padre.
      required:
        - entity_type_id
        - within
      properties:
        entity_type_id:
          type: string
          description: Tipo de entidades a devolver
          enum:
            - COUNTRY
            - STATE
            - MUNICIPALITY
            - ZIPCODE
            - LOCALITY
            - AGEB
            - URBAN_BLOCK
            - RURAL_BLOCK
            - NEIGHBORHOOD
          example: MUNICIPALITY
        within:
          type: object
          required:
            - entity_code
            - entity_type_id
          properties:
            entity_code:
              type: string
              description: Código de la entidad contenedora
              example: '16'
            entity_type_id:
              type: string
              description: Tipo de la entidad contenedora
              enum:
                - COUNTRY
                - STATE
                - MUNICIPALITY
                - ZIPCODE
                - LOCALITY
                - AGEB
                - URBAN_BLOCK
                - RURAL_BLOCK
                - NEIGHBORHOOD
              example: STATE
    LatestObservationItem:
      type: object
      properties:
        entity_id:
          type: string
          description: ID de la entidad (regresa como string)
          example: '1051'
        entity_code:
          type: string
          example: '16053'
        entity_name:
          type: string
          example: Morelia
        entity_type_id:
          type: string
          example: MUNICIPALITY
        indicator_id:
          type: string
          description: ID del indicador (regresa como string)
          example: '1528'
        indicator_name:
          type: string
          example: Población total
        indicator_name_en:
          type: string
          example: Total population
        value:
          type: number
          format: float
          example: 849053
        period:
          type: string
          example: '2020-01-01'
        parent_code:
          type: string
          example: '16'
        parent_name:
          type: string
          example: Michoacán de Ocampo
        parent_name_en:
          type: string
          example: Michoacán de Ocampo
        parent_entity_type_id:
          type: string
          example: STATE
        collection:
          $ref: '#/components/schemas/CollectionRef'
    CollectionRef:
      type: object
      nullable: true
      properties:
        collection_id:
          type: integer
          example: 501
        collection_name:
          type: string
          example: Niveles socioeconómicos
        collection_theme:
          type: string
          example: socioeconomic
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Token de autenticación. Formato requerido: Token tu-token (la palabra
        Token, un espacio y tu token). Solicita tu token escribiendo a
        contacto@tukanmx.com.

````