> ## 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.
# Listado por entidad
> Obtén los lugares individuales de una zona con su marca, institución, categorías y ubicación.
La versión granular de [conteo por entidad](/es/atlas/lugares/conteo-por-entidad). En lugar de conteos regresa **cada lugar individual** con su marca, institución, coordenadas y categorías, y solo incluye lugares activos.
Acepta el mismo `geo_filter` de tres modos (radio, dirección, entidad) y además un objeto `filters` para acotar por catálogo.
* `category_ids`, `brand_ids` e `institution_ids` incluyen solo esas categorías, marcas o instituciones.
* `exclude_category_ids`, `exclude_brand_ids` y `exclude_institution_ids` hacen lo contrario, todo excepto lo listado.
Los filtros se combinan con lógica **AND**. Resuelve los IDs en los [catálogos](/es/atlas/catalogos/marcas).
La paginación va en el cuerpo (`page`, `page_size`), con un máximo de **500 resultados por página**.
```bash cURL theme={null}
curl -X POST "https://client.tukanmx.com/tukan-atlas/places/detail/" \
-H "Authorization: Token $API_TUKAN" \
-H "Content-Type: application/json" \
-d '{
"geo_filter": {"latitude": 19.7060, "longitude": -101.1950, "radius_km": 2},
"filters": {"category_ids": ["bank"]},
"page_size": 100
}'
```
```python Python theme={null}
import os
import requests
headers = {"Authorization": f"Token {os.environ['API_TUKAN']}"}
# Bancos a 2 km del centro de Morelia
resp = requests.post(
"https://client.tukanmx.com/tukan-atlas/places/detail/",
headers=headers,
json={
"geo_filter": {"latitude": 19.7060, "longitude": -101.1950, "radius_km": 2},
"filters": {"category_ids": ["bank"]},
"page_size": 100,
},
)
resp.raise_for_status()
for lugar in resp.json()["results"][:3]:
print(lugar["brand_name"], lugar["geography"]["latitude"], lugar["geography"]["longitude"])
```
```json 200 theme={null}
{
"count": 34,
"page": 1,
"page_size": 100,
"geo_context": {
"state": "Michoacán de Ocampo",
"municipality": "Morelia",
"zipcode": "58000"
},
"results": [
{
"id": 76504,
"brand_id": 2650,
"brand_name": "BanBajío",
"brand_name_en": "BanBajío",
"institution_id": "BBA940707IE1.MX",
"institution_name": "Banco del Bajío",
"institution_name_en": "Banco del Bajío",
"legal_name": "Banco del Bajío, S.A., Institución de Banca Múltiple",
"geography": {
"latitude": 19.7023379,
"longitude": -101.2079899,
"state": "Michoacán de Ocampo"
},
"categories": ["Cajero automático", "Banco"]
}
]
}
```
## OpenAPI
````yaml es/atlas/openapi-atlas.json POST /places/detail/
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:
/places/detail/:
post:
summary: Densidad detallada
description: >-
Devuelve una lista paginada de lugares activos con todos sus detalles.
Soporta los mismos modos de geo_filter que densidad agrupada, mas
filtros opcionales de inclusión y exclusión por categoría, marca e
institución. Todos los filtros se combinan con lógica AND.
operationId: getPlacesDetail
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PlacesDetailRequest'
responses:
'200':
description: Lista de lugares obtenida exitosamente
content:
application/json:
schema:
$ref: '#/components/schemas/PlacesDetailResponse'
'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:
PlacesDetailRequest:
type: object
properties:
geo_filter:
$ref: '#/components/schemas/GeoFilter'
filters:
$ref: '#/components/schemas/PlacesFilter'
page:
type: integer
default: 1
page_size:
type: integer
default: 100
maximum: 500
PlacesDetailResponse:
type: object
properties:
count:
type: integer
page:
type: integer
page_size:
type: integer
geo_context:
$ref: '#/components/schemas/GeoContext'
results:
type: array
items:
$ref: '#/components/schemas/PlaceDetailItem'
ErrorResponse:
type: object
properties:
error:
type: string
GeoFilter:
type: object
description: >-
Filtro geográfico. Modos disponibles: radio (latitude, longitude,
radius_km), dirección (address, radius_km) o polígono (entity_type,
entity_codes).
properties:
latitude:
type: number
format: float
description: Latitud del centro (modo radio)
example: 19.706
longitude:
type: number
format: float
description: Longitud del centro (modo radio)
example: -101.195
radius_km:
type: number
format: float
description: Radio en kilómetros (modo radio o dirección)
example: 2
address:
type: string
description: Dirección a geocodificar. Requiere radius_km. (modo dirección)
example: Av. Madero Poniente 100, Centro, Morelia, Michoacán
entity_type:
type: string
description: Tipo de entidad geográfica (modo polígono)
enum:
- STATE
- MUNICIPALITY
- ZIPCODE
- LOCALITY
- NEIGHBORHOOD
- AGEB
- URBAN_BLOCK
- RURAL_BLOCK
- COUNTRY
example: ZIPCODE
entity_codes:
type: array
items:
type: string
description: Uno o mas códigos de entidad geográfica (modo polígono)
example:
- '58000'
PlacesFilter:
type: object
description: Filtros opcionales de inclusión/exclusión. Se combinan con lógica AND.
properties:
category_ids:
type: array
items:
type: string
example:
- bank
brand_ids:
type: array
items:
type: integer
institution_ids:
type: array
items:
type: string
exclude_category_ids:
type: array
items:
type: string
exclude_brand_ids:
type: array
items:
type: integer
example:
- 2637
exclude_institution_ids:
type: array
items:
type: string
GeoContext:
type: object
nullable: true
properties:
state:
type: string
nullable: true
example: Michoacán de Ocampo
municipality:
type: string
nullable: true
example: Morelia
zipcode:
type: string
nullable: true
example: '58000'
PlaceDetailItem:
type: object
properties:
id:
type: integer
brand_id:
type: integer
brand_name:
type: string
brand_name_en:
type: string
institution_id:
type: string
institution_name:
type: string
institution_name_en:
type: string
legal_name:
type: string
geography:
type: object
properties:
latitude:
type: number
longitude:
type: number
state:
type: string
nullable: true
categories:
type: array
items:
type: string
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.
````