> ## 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.
# Pinpoint masivo
> Resuelve hasta 10,000 coordenadas o 100 direcciones en una sola llamada.
La versión por lotes de [pinpoint individual](/es/atlas/pinpoint/individual), pensada para georreferenciar bases de datos completas en una sola llamada, como la cartera de sucursales o los domicilios de tus clientes.
* `coordinates` acepta hasta **10,000** pares `[latitud, longitud]`.
* `addresses` acepta hasta **100** direcciones en texto libre, que se resuelven automáticamente a coordenadas.
Los dos campos son mutuamente excluyentes. Cada resultado trae la misma jerarquía completa que el pinpoint individual y en el mismo orden del lote. La respuesta se pagina con `page` y `page_size` como parámetros de query. En modo direcciones, las que no se pudieron resolver aparecen en `geocode_errors` sin abortar el resto.
También acepta `valid_to` en el cuerpo para resolver contra cartografía histórica.
```bash cURL theme={null}
curl -X POST "https://client.tukanmx.com/tukan-atlas/pinpoint/" \
-H "Authorization: Token $API_TUKAN" \
-H "Content-Type: application/json" \
-d '{
"coordinates": [
[19.7060, -101.1950],
[19.4326, -99.1332]
]
}'
```
```python Python theme={null}
import os
import requests
headers = {"Authorization": f"Token {os.environ['API_TUKAN']}"}
resp = requests.post(
"https://client.tukanmx.com/tukan-atlas/pinpoint/",
headers=headers,
json={"coordinates": [[19.7060, -101.1950], [19.4326, -99.1332]]},
)
resp.raise_for_status()
for punto in resp.json()["results"]:
print(punto["municipality"], punto["zipcode"])
```
```json 200 theme={null}
{
"count": 2,
"page": 1,
"page_size": 100,
"results": [
{
"latitude": 19.706,
"longitude": -101.195,
"country": "México",
"country_code": "mex",
"state": "Michoacán de Ocampo",
"state_code": "16",
"municipality": "Morelia",
"municipality_code": "16053",
"zipcode": "58000",
"locality": "Morelia",
"locality_code": "160530001",
"ageb": "1605300010293",
"urban_block": "1605300010293008",
"neighborhood": "Centro Histórico",
"neighborhood_code": "1605300010057"
}
]
}
```
## OpenAPI
````yaml es/atlas/openapi-atlas.json POST /pinpoint/
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:
/pinpoint/:
post:
summary: Pinpoint masivo
description: >-
Procesa hasta 10,000 coordenadas en una sola llamada. Todos los puntos
se resuelven contra la cartografía de México. El resultado se devuelve
en el mismo orden que el input. Si un punto cae fuera de la cobertura,
se incluye un campo error en lugar de los campos geográficos.
operationId: pinpointBulk
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
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PinpointBulkRequest'
responses:
'200':
description: Geocodificación masiva completada
content:
application/json:
schema:
$ref: '#/components/schemas/PinpointBulkResponse'
'400':
description: >-
Solicitud inválida - coordenadas faltantes, vacías, mas de 10,000
items o formato incorrecto
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:
PinpointBulkRequest:
type: object
required:
- coordinates
properties:
coordinates:
type: array
items:
type: array
items:
type: number
minItems: 2
maxItems: 2
minItems: 1
maxItems: 10000
description: Lista de pares [latitud, longitud]. Máximo 10,000.
example:
- - 19.706
- -101.195
- - 19.4326
- -99.1332
valid_to:
type: string
format: date
description: >-
Fecha para consultar versión histórica de polígonos (YYYY-MM-DD).
Omitir para la versión actual.
example: '2022-06-01'
addresses:
type: array
maxItems: 100
description: >-
Hasta 100 direcciones en texto libre. Se resuelven automáticamente a
coordenadas. Mutuamente excluyente con coordinates.
items:
type: string
example:
- Av. Madero Poniente 100, Centro, Morelia, Michoacán
PinpointBulkResponse:
type: object
properties:
count:
type: integer
example: 2
page:
type: integer
example: 1
page_size:
type: integer
example: 100
results:
type: array
items:
$ref: '#/components/schemas/PinpointBulkItem'
geocode_errors:
type: array
description: Direcciones que no se pudieron geocodificar (solo en modo addresses)
items:
$ref: '#/components/schemas/GeocodeError'
ErrorResponse:
type: object
properties:
error:
type: string
PinpointBulkItem:
type: object
properties:
latitude:
type: number
longitude:
type: number
country:
type: string
nullable: true
country_code:
type: string
nullable: true
state:
type: string
nullable: true
state_code:
type: string
nullable: true
municipality:
type: string
nullable: true
municipality_code:
type: string
nullable: true
zipcode:
type: string
nullable: true
locality:
type: string
nullable: true
locality_code:
type: string
nullable: true
ageb:
type: string
nullable: true
urban_block:
type: string
nullable: true
rural_block:
type: string
nullable: true
neighborhood:
type: string
nullable: true
neighborhood_code:
type: string
nullable: true
error:
type: string
nullable: true
description: Presente solo si el punto cae fuera de la cobertura de México
GeocodeError:
type: object
description: >-
Dirección que no se pudo resolver a coordenadas (solo en modo
addresses).
properties:
address:
type: string
error:
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.
````