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

> Convierte una coordenada en su jerarquía geográfica completa: del estado a la manzana.

Manda una latitud y una longitud, y recibe la entidad que contiene ese punto en cada nivel de la jerarquía, desde el país hasta la manzana.

Hay dos detalles del formato de respuesta que conviene conocer.

* Cada nivel trae su nombre y su código (`state` y `state_code`). Cuando el nombre y el código son lo mismo, como en `zipcode`, el campo `_code` se omite.
* Si el punto cae exactamente en la frontera de dos entidades gana la de **menor área**, así que la respuesta siempre es una sola jerarquía.

Con `valid_to` puedes resolver el punto contra la cartografía vigente en una **fecha pasada**, útil si trabajas con datos históricos y los límites cambiaron desde entonces.

<Tip>
  ¿Tienes miles de puntos o direcciones en texto?

  Usa [pinpoint masivo](/es/atlas/pinpoint/masivo) que acepta hasta 10,000 coordenadas o 100 direcciones por llamada.
</Tip>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://client.tukanmx.com/tukan-atlas/pinpoint/?latitude=19.7060&longitude=-101.1950" \
    -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/pinpoint/",
      headers=headers,
      params={"latitude": 19.7060, "longitude": -101.1950},
  )
  resp.raise_for_status()
  punto = resp.json()
  print(punto["municipality"], punto["zipcode"], punto["neighborhood"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml es/atlas/openapi-atlas.json GET /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/:
    get:
      summary: Pinpoint individual
      description: >-
        Dado un par de coordenadas, devuelve todas las entidades geográficas que
        contienen el punto: país, estado, municipio, código postal, localidad,
        AGEB, manzana y colonia. Por defecto usa los polígonos vigentes. Con
        valid_to puedes consultar la versión histórica activa en esa fecha.
      operationId: pinpointSingle
      parameters:
        - name: latitude
          in: query
          description: Latitud decimal
          required: true
          schema:
            type: number
            format: float
            example: 19.7058
        - name: longitude
          in: query
          description: Longitud decimal
          required: true
          schema:
            type: number
            format: float
            example: -101.1949
        - name: valid_to
          in: query
          description: >-
            Fecha para consultar la versión histórica de polígonos activa en esa
            fecha (YYYY-MM-DD). Omitir para la versión actual.
          required: false
          schema:
            type: string
            format: date
            example: '2022-06-01'
      responses:
        '200':
          description: Entidades geográficas del punto obtenidas exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinpointResponse'
        '400':
          description: >-
            Coordenadas inválidas, fuera de rango o fuera de la cobertura de
            México
          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:
    PinpointResponse:
      type: object
      properties:
        country:
          type: string
          example: México
        country_code:
          type: string
          example: mex
        state:
          type: string
          example: Michoacán de Ocampo
        state_code:
          type: string
          example: '16'
        municipality:
          type: string
          example: Morelia
        municipality_code:
          type: string
          example: '16053'
        zipcode:
          type: string
          example: '58000'
        locality:
          type: string
          example: Morelia
        locality_code:
          type: string
          example: '160530001'
        ageb:
          type: string
          example: '1605300010293'
        urban_block:
          type: string
          example: '1605300010293008'
        rural_block:
          type: string
          nullable: true
        neighborhood:
          type: string
          nullable: true
          example: Centro Histórico
        neighborhood_code:
          type: string
          nullable: true
          example: '1605300010057'
    ErrorResponse:
      type: object
      properties:
        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.

````