> ## 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.
# Polígonos
> Las versiones vigentes e históricas de la geometría de cada entidad, con su bounding box y centroide.
Consulta el polígono de una entidad geográfica con su área en km², su **bounding box** y su **centroide**.
Como los límites cambian con el tiempo, una misma entidad tiene varias versiones con su vigencia (`valid_from` y `valid_to`). La regla de oro es que **`valid_to` en `null` es la versión vigente hoy**, así que para casi cualquier análisis conviene filtrar `?valid_to=null`.
Con el bbox y el centroide resuelves los casos de mapa más comunes.
* **Centrar y hacer zoom**, porque el bbox define el encuadre exacto de la entidad.
* **Colocar un marcador o etiqueta**, usando el centroide como punto representativo.
* **Filtrar espacialmente**, descartando entidades cuyo bbox ni siquiera intersecta tu área de interés antes de hacer cálculos finos.
La API **no regresa la geometría completa** del polígono. Si necesitas medir algo dentro de un área, manda tu propio polígono a [estadísticas por polígono](/es/atlas/estadisticas/estadisticas-por-poligono) y Atlas calcula los indicadores por ti.
```bash cURL theme={null}
curl "https://client.tukanmx.com/tukan-atlas/polygons/detailed/?entity_type_id=MUNICIPALITY&entity_code=16053&valid_to=null" \
-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/polygons/detailed/",
headers=headers,
params={
"entity_type_id": "MUNICIPALITY",
"entity_code": "16053",
"valid_to": "null",
},
)
resp.raise_for_status()
p = resp.json()["results"][0]
print("centro:", p["centroid_lat"], p["centroid_lon"])
```
```json 200 theme={null}
{
"count": 1,
"page": 1,
"page_size": 100,
"results": [
{
"polygon_code": "mex_municipality_16053_20250101",
"entity_type_id": "MUNICIPALITY",
"entity_code": "16053",
"valid_from": "2025-01-01",
"valid_to": null,
"area_km2": 1184.81,
"source_id": "MEX_INEGI",
"bbox_west": -101.5089,
"bbox_east": -101.0426,
"bbox_south": 19.4472,
"bbox_north": 19.8623,
"centroid_lon": -101.2791,
"centroid_lat": 19.6666
}
]
}
```
## OpenAPI
````yaml es/atlas/openapi-atlas.json GET /polygons/detailed/
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:
/polygons/detailed/:
get:
summary: Catálogo de polígonos
description: >-
Lista los polígonos geográficos con información espacial adicional:
bounding box (bbox_west, bbox_east, bbox_south, bbox_north) y centroide
(centroid_lon, centroid_lat). Soporta los mismos filtros que el catálogo
de polígonos.
operationId: listPolygonsDetailed
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: entity_type_id
in: query
description: Tipo de entidad geográfica del polígono
required: false
schema:
type: string
enum:
- COUNTRY
- STATE
- MUNICIPALITY
- ZIPCODE
- LOCALITY
- AGEB
- URBAN_BLOCK
- RURAL_BLOCK
- NEIGHBORHOOD
example: ZIPCODE
- name: entity_code
in: query
description: Código geográfico de la entidad (coincidencia exacta)
required: false
schema:
type: string
example: '16053'
- name: polygon_code
in: query
description: Código único del polígono (coincidencia exacta)
required: false
schema:
type: string
example: mex_municipality_16053_20250101
- name: source_id
in: query
description: Fuente del polígono (coincidencia exacta)
required: false
schema:
type: string
example: MEX_INEGI
- name: valid_to
in: query
description: >-
Fecha de expiración del polígono (YYYY-MM-DD). Usa null para filtrar
solo polígonos vigentes.
required: false
schema:
type: string
example: 'null'
- name: valid_from
in: query
description: Fecha de inicio de validez del polígono (YYYY-MM-DD)
required: false
schema:
type: string
format: date
example: '2020-01-01'
- name: search
in: query
description: Búsqueda global en polygon_code y entity_code
required: false
schema:
type: string
responses:
'200':
description: Polígonos con detalle espacial obtenidos exitosamente
content:
application/json:
schema:
$ref: '#/components/schemas/PolygonDetailedListResponse'
'401':
description: Token de autenticación inválido o ausente
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
PolygonDetailedListResponse:
type: object
properties:
count:
type: integer
page:
type: integer
page_size:
type: integer
results:
type: array
items:
$ref: '#/components/schemas/PolygonDetailedItem'
ErrorResponse:
type: object
properties:
error:
type: string
PolygonDetailedItem:
type: object
properties:
polygon_code:
type: string
example: mex_municipality_16053_20250101
entity_code:
type: string
nullable: true
example: '16053'
entity_type_id:
type: string
example: MUNICIPALITY
valid_from:
type: string
format: date
example: '2025-01-01'
valid_to:
type: string
format: date
nullable: true
area_km2:
type: number
format: float
nullable: true
example: 1184.81
source_id:
type: string
nullable: true
example: MEX_INEGI
bbox_west:
type: number
format: float
description: Longitud mínima del bounding box
example: -101.5089
bbox_east:
type: number
format: float
description: Longitud máxima del bounding box
example: -101.0426
bbox_south:
type: number
format: float
description: Latitud mínima del bounding box
example: 19.4472
bbox_north:
type: number
format: float
description: Latitud máxima del bounding box
example: 19.8623
centroid_lon:
type: number
format: float
description: Longitud del centroide del polígono
example: -101.2791
centroid_lat:
type: number
format: float
description: Latitud del centroide del polígono
example: 19.6666
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.
````