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

# Instituciones

> Las empresas dueñas de las marcas mapeadas en Atlas, identificadas por RFC.

Las empresas dueñas de las [marcas](/es/atlas/catalogos/marcas), identificadas por un ID tipo RFC. Una institución puede operar varias marcas.

Usa su `id` para filtrar por grupo corporativo completo en [listado por entidad](/es/atlas/lugares/listado-por-entidad) (`filters.institution_ids`), o para listar sus marcas en [marcas](/es/atlas/catalogos/marcas).

<RequestExample>
  ```bash cURL theme={null}
  curl "https://client.tukanmx.com/tukan-atlas/institution-entities/?search=oxxo" \
    -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/institution-entities/",
      headers=headers,
      params={"search": "oxxo"},
  )
  resp.raise_for_status()
  for inst in resp.json()["results"]:
      print(inst["id"], inst["name"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "count": 1,
    "page": 1,
    "page_size": 100,
    "results": [
      {
        "id": "CCO8605231N4.MX",
        "name": "Cadena Comercial OXXO",
        "name_en": "Cadena Comercial OXXO",
        "legal_name": "Cadena Comercial OXXO, S.A. de C.V."
      }
    ]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml es/atlas/openapi-atlas.json GET /institution-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:
  /institution-entities/:
    get:
      summary: Catálogo de instituciones
      description: >-
        Lista las instituciones que operan lugares en Atlas. Una institución
        puede tener varias marcas. Usa institution_id en los filtros de densidad
        de lugares o para listar las marcas de una institución en brands/.
      operationId: listInstitutionEntities
      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 id, name, name_en y legal_name
          required: false
          schema:
            type: string
            example: hsbc
        - name: id
          in: query
          description: ID exacto de la institución (tipo RFC)
          required: false
          schema:
            type: string
            example: FAR970429SE2.MX
        - name: name
          in: query
          description: Filtro por nombre de la institución (coincidencia parcial)
          required: false
          schema:
            type: string
            example: banco
        - name: name_en
          in: query
          description: Filtro por razón social en inglés (coincidencia parcial)
          required: false
          schema:
            type: string
        - name: legal_name
          in: query
          description: Filtro por razón social (coincidencia parcial)
          required: false
          schema:
            type: string
            example: HSBC
      responses:
        '200':
          description: Catálogo obtenido exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstitutionListResponse'
        '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:
    InstitutionListResponse:
      type: object
      properties:
        count:
          type: integer
        page:
          type: integer
          example: 1
        page_size:
          type: integer
          example: 100
        results:
          type: array
          items:
            $ref: '#/components/schemas/InstitutionItem'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
    InstitutionItem:
      type: object
      properties:
        id:
          type: string
          description: Identificador tipo RFC
          example: CCO8605231N4.MX
        name:
          type: string
          example: Cadena Comercial OXXO
          description: Nombre de la institución
        name_en:
          type: string
          example: Cadena Comercial OXXO
        legal_name:
          type: string
          nullable: true
          description: Razón social completa
          example: Cadena Comercial OXXO, S.A. de C.V.
  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.

````