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

# Entidades

> Encuentra cualquier entidad geográfica de México por nombre, código o jerarquía.

Busca cualquier entidad geográfica de México por nombre, código o jerarquía.

Es el endpoint que usas para resolver *"¿cuál es el `entity_id` de Morelia?"* antes de pedir [observaciones](/es/atlas/estadisticas/ultimas-observaciones). Los dos patrones más comunes son estos.

* **Resolver una entidad por nombre**. Combina `entity_type_id` con `name`, como en `?entity_type_id=MUNICIPALITY&name=morelia`.
* **Listar las hijas de una entidad**. Usa `parent_code`, como en `?entity_type_id=MUNICIPALITY&parent_code=16`, que regresa los 113 municipios de Michoacán.

<Warning>
  Los filtros por campo tienen **prioridad** sobre `search`. Si mandas cualquier filtro (`entity_type_id`, `name`, `parent_code`…), el parámetro `search` se ignora por completo. Para acotar por tipo *y* nombre a la vez, usa `entity_type_id` + `name`, no `entity_type_id` + `search`.
</Warning>

<Tip>
  Para saber qué entidades rodean a la que encontraste, usa [entidades vecinas](/es/atlas/catalogos/entidades-vecinas). Para sus indicadores, como población, nivel socioeconómico o precios, pásale el `entity_id` a [últimas observaciones](/es/atlas/estadisticas/ultimas-observaciones).
</Tip>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://client.tukanmx.com/tukan-atlas/geo-entities/?entity_type_id=MUNICIPALITY&name=morelia" \
    -H "Authorization: Token $API_TUKAN"
  ```

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

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

  resp = requests.get(
      "https://client.tukanmx.com/tukan-atlas/geo-entities/",
      headers=headers,
      params={"entity_type_id": "MUNICIPALITY", "name": "morelia"},
  )
  resp.raise_for_status()
  entity = resp.json()["results"][0]
  print(entity["entity_id"], entity["entity_code"], entity["name"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "count": 1,
    "page": 1,
    "page_size": 100,
    "results": [
      {
        "entity_id": 1051,
        "entity_code": "16053",
        "entity_type_id": "MUNICIPALITY",
        "name": "Morelia",
        "name_en": "Morelia",
        "parent_code": "16",
        "parent_name": "Michoacán de Ocampo"
      }
    ]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml es/atlas/openapi-atlas.json GET /geo-entities/
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:
  /geo-entities/:
    get:
      summary: Búsqueda de entidades geográficas
      description: >-
        Lista y busca entidades geográficas de México. Niveles disponibles:
        país, estados, municipios, códigos postales, localidades, AGEBs,
        manzanas y colonias. Filtra por entity_type_id para obtener un nivel
        específico, y por parent_code para listar entidades hijas de una entidad
        padre.
      operationId: listGeoEntities
      parameters:
        - name: page
          in: query
          description: Número de página
          required: false
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          description: Resultados por página
          required: false
          schema:
            type: integer
            default: 100
        - name: search
          in: query
          description: Búsqueda global en entity_code, name, name_en y parent_code
          required: false
          schema:
            type: string
            example: morelia
        - name: entity_code
          in: query
          description: Código geográfico exacto de la entidad
          required: false
          schema:
            type: string
            example: '16053'
        - name: entity_type_id
          in: query
          description: Tipo de entidad geográfica (coincidencia exacta)
          required: false
          schema:
            type: string
            enum:
              - COUNTRY
              - STATE
              - MUNICIPALITY
              - ZIPCODE
              - LOCALITY
              - AGEB
              - URBAN_BLOCK
              - RURAL_BLOCK
              - NEIGHBORHOOD
            example: MUNICIPALITY
        - name: name
          in: query
          description: Filtro por nombre en español (coincidencia parcial)
          required: false
          schema:
            type: string
            example: morelia
        - name: name_en
          in: query
          description: Filtro por nombre en inglés (coincidencia parcial)
          required: false
          schema:
            type: string
            example: méxico city
        - name: parent_code
          in: query
          description: >-
            Código de la entidad padre (coincidencia exacta). Útil para listar
            todos los municipios de un estado.
          required: false
          schema:
            type: string
            example: '09'
      responses:
        '200':
          description: Entidades geográficas obtenidas exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoEntityListResponse'
        '401':
          description: Token de autenticación inválido o ausente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    GeoEntityListResponse:
      type: object
      properties:
        count:
          type: integer
        page:
          type: integer
        page_size:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/GeoEntityItem'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
    GeoEntityItem:
      type: object
      properties:
        entity_id:
          type: integer
          example: 1051
        entity_code:
          type: string
          example: '16053'
        entity_type_id:
          type: string
          example: MUNICIPALITY
        name:
          type: string
          example: Morelia
        name_en:
          type: string
          example: Morelia
        parent_code:
          type: string
          nullable: true
          example: '16'
        parent_name:
          type: string
          description: Nombre de la entidad padre
          example: Michoacán de Ocampo
  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.

````