> ## 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.
# Estadísticas por polígono
> Estima el valor de cualquier indicador dentro de un polígono arbitrario y compáralo contra su entorno.
Calcula el estimado para una lista de indicadores para un polígono arbitrario.
Es la forma más completa de enriquecer la información alrededor de un punto. Para utilizarlo es necesario mandar **cualquier polígono GeoJSON** junto con una lista de indicadores. A cambio recibes lo siguiente.
* Una estimación de cada indicador *dentro* del polígono. Únicamente disponible para indicadores con observaciones a nivel código postal.
* **El entorno completo** el valor observado del indicador para los códigos postales, municipios, estado y país que el polígono toca, en unidades completas.
* **`vs_context`** trae la comparación del estimado contra cada nivel, según la naturaleza del indicador.
| `method` | Cuándo aplica | Cómo leerlo |
| ------------ | ------------------------------ | -------------------------------------------- |
| `share` | Conteos (población, viviendas) | Qué proporción del total captura tu polígono |
| `difference` | Tasas y porcentajes | Puntos de diferencia contra el nivel |
| `ratio` | Promedios (precios) | Cuántas veces el valor del nivel |
Un indicador solo aparece en la respuesta si tiene observaciones a nivel código postal. Los que no las tienen se omiten sin error. Si un indicador que pediste no viene en `data`, esa es la causa.
```bash cURL theme={null}
curl -X POST "https://client.tukanmx.com/tukan-atlas/polygon-context/" \
-H "Authorization: Token $API_TUKAN" \
-H "Content-Type: application/json" \
-d '{
"polygon": {
"type": "Polygon",
"coordinates": [[
[-101.21, 19.69], [-101.18, 19.69],
[-101.18, 19.715], [-101.21, 19.715],
[-101.21, 19.69]
]]
},
"indicators": [1528, 3701, 3201]
}'
```
```python Python theme={null}
import os
import requests
headers = {"Authorization": f"Token {os.environ['API_TUKAN']}"}
# Población, % NSE alto y precio de renta en el centro de Morelia
resp = requests.post(
"https://client.tukanmx.com/tukan-atlas/polygon-context/",
headers=headers,
json={
"polygon": {
"type": "Polygon",
"coordinates": [[
[-101.21, 19.69], [-101.18, 19.69],
[-101.18, 19.715], [-101.21, 19.715],
[-101.21, 19.69],
]],
},
"indicators": [1528, 3701, 3201],
},
)
resp.raise_for_status()
for ind_id, r in resp.json()["data"].items():
print(r["mnemonic"], r["estimate"])
```
```json 200 theme={null}
{
"data": {
"1528": {
"mnemonic": "census_population",
"unit": "PEOPLE",
"estimate": 83448.5209,
"zipcode": 133966.622,
"municipality": 849053.0,
"state": 4748846.0,
"national": 126014024.0,
"vs_context": {
"method": "share",
"zipcode": 0.6229,
"municipality": 0.0983,
"state": 0.0176,
"national": 0.0007
}
},
"3701": {
"mnemonic": "pct_households_nse_high",
"unit": "PERCENT",
"estimate": 0.3095,
"zipcode": 0.3254,
"municipality": 0.3078,
"state": 0.1483,
"national": 0.1875,
"vs_context": {
"method": "difference",
"zipcode": -0.0159,
"municipality": 0.0017,
"state": 0.1612,
"national": 0.122
}
}
},
"context": {
"zipcode": [
{"entity_code": "58030", "f_wp": 0.7202},
{"entity_code": "58168", "f_wp": 1.0},
{"entity_code": "58000", "f_wp": 0.9463}
],
"municipality": ["16053"],
"state": ["16"]
}
}
```
## OpenAPI
````yaml es/atlas/openapi-atlas.json POST /polygon-context/
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:
/polygon-context/:
post:
summary: Contexto de polígono
description: >-
Manda cualquier polígono GeoJSON (una isócrona, un radio, un área
dibujada a mano) y una lista de indicadores. Regresa el valor estimado
de cada indicador dentro del polígono y su comparación contra los
códigos postales, municipios, estado y país que toca.
operationId: getPolygonContext
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PolygonContextRequest'
responses:
'200':
description: Contexto calculado exitosamente
content:
application/json:
schema:
$ref: '#/components/schemas/PolygonContextResponse'
'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:
PolygonContextRequest:
type: object
required:
- polygon
- indicators
description: >-
Polígono GeoJSON (Polygon o MultiPolygon) y lista de indicadores a
estimar dentro de el.
properties:
polygon:
type: object
required:
- type
- coordinates
description: >-
Objeto GeoJSON. Acepta Polygon o MultiPolygon, con hoyos si aplica.
Puede venir de una isócrona, un radio, un polígono dibujado a mano o
la geometría de cualquier entidad de Atlas.
properties:
type:
type: string
enum:
- Polygon
- MultiPolygon
example: Polygon
coordinates:
type: array
items: {}
description: Coordenadas GeoJSON en orden [longitud, latitud]
example:
- - - -101.2
- 19.68
- - -101.15
- 19.68
- - -101.15
- 19.73
- - -101.2
- 19.73
- - -101.2
- 19.68
indicators:
type: array
items:
type: integer
minItems: 1
description: >-
IDs de indicadores. Solo se incluyen en la respuesta los indicadores
que tienen observaciones a nivel código postal.
example:
- 1528
- 3701
- 3201
PolygonContextResponse:
type: object
properties:
data:
type: object
description: Resultados por indicador, con el indicator_id como llave
additionalProperties:
$ref: '#/components/schemas/PolygonContextIndicatorResult'
context:
type: object
description: Entidades que el polígono toca en cada nivel
properties:
zipcode:
type: array
description: >-
Códigos postales que toca el polígono, con su factor de
ponderación.
items:
type: object
properties:
entity_code:
type: string
example: '58030'
f_wp:
type: number
example: 0.7202
description: >-
Factor de ponderación del código postal dentro del
polígono.
municipality:
type: array
items:
type: string
description: Códigos de municipio tocados
example:
- '16053'
state:
type: array
items:
type: string
description: Códigos de estado tocados
example:
- '16'
ErrorResponse:
type: object
properties:
error:
type: string
PolygonContextIndicatorResult:
type: object
description: >-
Valor estimado de un indicador dentro del polígono y su comparativa
contra el entorno.
properties:
mnemonic:
type: string
example: census_population
unit:
type: string
example: PEOPLE
estimate:
type: number
nullable: true
description: Valor estimado del indicador dentro del polígono.
example: 83448.5209
zipcode:
type: number
nullable: true
description: >-
Valor combinado de todos los códigos postales que el polígono toca
(unidades completas)
example: 133966.622
municipality:
type: number
nullable: true
description: Valor combinado de los municipios que el polígono toca
example: 849053
state:
type: number
nullable: true
description: Valor combinado de los estados que el polígono toca
example: 4748846
national:
type: number
nullable: true
description: Valor nacional
example: 126014024
vs_context:
type: object
description: >-
Comparativa del valor estimado contra cada nivel: share (conteos),
difference (tasas y porcentajes) o ratio (promedios).
properties:
method:
type: string
enum:
- share
- difference
- ratio
example: share
zipcode:
type: number
nullable: true
example: 0.6229
municipality:
type: number
nullable: true
example: 0.0983
state:
type: number
nullable: true
example: 0.0176
national:
type: number
nullable: true
example: 0.0007
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.
````