API de Panoramas 360° del Perú — Documentación

Introducción

La API pública de AeroStitch 360 permite consultar la colección de panoramas equirectangulares 360° del Perú, subidos por usuarios que los marcaron como públicos. Los datos incluyen coordenadas GPS, departamento, autor y una URL directa a la imagen.

ℹ️ No se requiere registro ni clave de API para acceder a los endpoints públicos. Para publicar panoramas sí se necesita una cuenta.

⚠️ La API está en fase beta. La estructura puede evolucionar — usa el campo id como identificador estable.

URL base

https://aerostitch360.com

Todos los endpoints responden con Content-Type: application/json y codificación UTF-8. No hay CORS restrictivo — puedes llamarlos desde cualquier origen.

Endpoints

Listar panoramas

GET /api/v1/panoramas Paginado · sin auth

Parámetros de consulta (opcionales)

Parámetro	Tipo	Default	Descripción
dept	`string`	—	Filtrar por departamento (ej: `Cusco`)
page	`integer`	1	Número de página
limit	`integer`	50	Resultados por página (máx. 200)

Ejemplo de respuesta

{
  "data": [
    {
      "id": 1,
      "title": "Vista desde Machu Picchu",
      "place_name": "Machu Picchu",
      "department": "Cusco",
      "district": "Aguas Calientes",
      "lat": -13.1631,
      "lng": -72.5450,
      "image_url": "https://aerostitch360.com/uploads/panoramas/pano_1_1718000000.jpg",
      "view_count": 42,
      "featured": 0,
      "author_name": "Juan García",
      "created_at": "2026-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "total": 87,
    "page": 1,
    "limit": 50,
    "pages": 2
  }
}

Obtener panorama individual

GET /api/v1/panoramas/:id Incrementa vistas · sin auth

Parámetros de ruta

Parámetro	Tipo	Descripción
id	`integer`	ID único del panorama

Ejemplo

GET /api/v1/panoramas/1

Respuesta 200

{
  "id": 1,
  "title": "Vista desde Machu Picchu",
  "description": "Panorama tomado al amanecer desde la Puerta del Sol.",
  "place_name": "Machu Picchu",
  "department": "Cusco",
  "lat": -13.1631,
  "lng": -72.5450,
  "image_url": "https://aerostitch360.com/uploads/panoramas/pano_1_1718000000.jpg",
  "view_count": 43,
  "author_name": "Juan García",
  "created_at": "2026-01-15T10:30:00.000Z"
}

Embed — visor iframe

Incrusta cualquier panorama público en tu web con un simple <iframe>. El visor soporta drag, scroll-zoom y touch. No requiere JavaScript propio.

<iframe
  src="https://aerostitch360.com/embed?id=1"
  width="800"
  height="450"
  frameborder="0"
  allowfullscreen
  loading="lazy"
  title="Panorama 360° — AeroStitch 360"
></iframe>

🌐

El visor se muestra aquí en tiempo real cuando hay un panorama disponible

Ver galería para encontrar un ID →

El parámetro ?id= corresponde al campo id de la API. Cada carga del iframe incrementa el contador de vistas del panorama.

Esquema de respuesta

Campo	Tipo	Descripción
id	`integer`	Identificador único del panorama
title	`string`	Nombre descriptivo del panorama
description	`string\|null`	Descripción larga (puede ser nulo)
place_name	`string\|null`	Nombre del lugar geográfico
department	`string\|null`	Departamento del Perú
district	`string\|null`	Distrito específico
lat	`number\|null`	Latitud decimal (WGS84)
lng	`number\|null`	Longitud decimal (WGS84)
image_url	`string`	URL absoluta de la imagen equirectangular JPG
view_count	`integer`	Número de veces que se ha visualizado
featured	`0\|1`	Destacado por el administrador
author_name	`string`	Nombre público del fotógrafo
created_at	`ISO 8601`	Fecha de publicación

Códigos de estado HTTP

200

OK — respuesta exitosa

400

Bad Request — parámetro inválido

404

Not Found — panorama no existe o es privado

500

Internal Error — error del servidor

Departamentos disponibles

Usa el nombre exacto (con tilde) como valor del parámetro dept:

Cusco · Lima · Arequipa · Puno · Ica · Áncash · La Libertad
Lambayeque · Loreto · Piura · San Martín · Amazonas · Cajamarca
Junín · Ucayali · Madre de Dios · Apurímac · Huancavelica
Huánuco · Moquegua · Pasco · Tacna · Tumbes · Ayacucho

Límites y uso justo

No hay autenticación requerida, pero aplicamos rate-limiting razonable para garantizar disponibilidad:

Tipo de uso	Límite
Lecturas de lista / panorama individual	300 req / 5 minutos por IP
Carga de imagen (image_url)	Sin límite adicional — CDN
Embed iframes	Sin límite

Para uso intensivo o integración comercial, escríbenos a hola@aerostitch360.com para coordinar acceso prioritario.

Ejemplos de código

JavaScript (fetch)

// Obtener panoramas de Cusco
const res = await fetch('https://aerostitch360.com/api/v1/panoramas?dept=Cusco&limit=10');
const { data, meta } = await res.json();
console.log(`${meta.total} panoramas encontrados`);
data.forEach(p => console.log(p.title, p.image_url));

PHP

$url = 'https://aerostitch360.com/api/v1/panoramas?dept=Lima';
$response = json_decode(file_get_contents($url), true);
foreach ($response['data'] as $panorama) {
    echo $panorama['title'] . ' — ' . $panorama['image_url'] . "\n";
}

Leaflet.js — mapa interactivo

// Marcar todos los panoramas en un mapa Leaflet
const map = L.map('map').setView([-9.19, -75.02], 5);
L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png').addTo(map);

const res = await fetch('/api/v1/panoramas?limit=200');
const { data } = await res.json();

data.filter(p => p.lat && p.lng).forEach(p => {
    L.marker([p.lat, p.lng])
        .addTo(map)
        .bindPopup(`
            <strong>${p.title}</strong><br>
            <a href="https://aerostitch360.com/embed?id=${p.id}" target="_blank">
                Ver 360° →
            </a>
        `);
});