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

> Obtén todas las entidades que comparten frontera con una entidad dada, al mismo nivel o a otro.

Regresa las entidades que **comparten frontera** con la entidad que indiques.

Sirve para extender un análisis a la zona de influencia real de una entidad, porque el área metropolitana de una ciudad rara vez respeta el límite municipal. Por default los vecinos son del mismo nivel; con `entity_type_id` puedes pedir otro, como los municipios que colindan con un estado.

<Note>
  Disponible para los niveles `STATE`, `MUNICIPALITY` y `ZIPCODE`.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  # Municipios que colindan con Morelia (mismo nivel — default)
  curl "https://client.tukanmx.com/tukan-atlas/geo-entities/1051/borders/" \
    -H "Authorization: Token $API_TUKAN"
  ```

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

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

  # Municipios que colindan con Morelia (entity_id 1051)
  resp = requests.get(
      "https://client.tukanmx.com/tukan-atlas/geo-entities/1051/borders/",
      headers=headers,
  )
  resp.raise_for_status()
  for vecino in resp.json()["results"][:3]:
      print(vecino["entity_code"], vecino["name"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "count": 14,
    "results": [
      {
        "entity_id": 1083,
        "entity_code": "16001",
        "entity_type_id": "MUNICIPALITY",
        "name": "Acuitzio",
        "name_en": "Acuitzio",
        "parent_code": "16",
        "parent_name": "Michoacán de Ocampo"
      }
    ]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml es/atlas/openapi-atlas.json GET /geo-entities/{entity_id}/borders/
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/{entity_id}/borders/:
    get:
      summary: Entidades colindantes
      description: >-
        Regresa todas las entidades geográficas que comparten frontera con la
        entidad dada. Por default regresa vecinos del mismo nivel (estados que
        colindan con un estado); con entity_type_id puedes pedir vecinos de otro
        nivel (municipios que colindan con un estado).
      operationId: getGeoEntityBorders
      parameters:
        - name: entity_id
          in: path
          required: true
          description: ID de la entidad geográfica
          schema:
            type: integer
            example: 1
        - name: entity_type_id
          in: query
          description: >-
            Tipo de los vecinos a regresar. Default: el mismo tipo que la
            entidad consultada.
          required: false
          schema:
            type: string
            enum:
              - STATE
              - MUNICIPALITY
              - ZIPCODE
            example: MUNICIPALITY
      responses:
        '200':
          description: Entidades colindantes obtenidas exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoEntityBordersResponse'
        '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'
        '404':
          description: Entidad no encontrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    GeoEntityBordersResponse:
      type: object
      properties:
        count:
          type: integer
          example: 3
        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.

````