API de Bus Sun Side Online

Qué lado de un autocar recibe sol o sombra en un viaje, y qué asientos son mejores para la sombra o para las vistas. El viaje se recorre en pasos de 5 minutos: posición y rumbo según la ruta, posición del sol en ese lugar y a esa hora, y luego una estimación por asiento para la distribución de autobús elegida. Use una ruta de nuestro registro de líneas autorizadas (route_id), dos puntos (from/to) o envíe con POST su propia ruta (paradas o una polyline) para obtener también un mapa de asientos, un mapa de la ruta y una cronología como imágenes. Los resultados son una estimación a partir de la geometría y la posición del sol; la sombra real también depende de cortinas, edificios, relieve y meteorología.

GET https://nakordoni.eu/api/v2/data/bus-sun-side — clase de cuota: heavy

Campos de la respuesta — dentro del objeto data del sobre de respuesta. [] indica una lista, así que data.items[].name es el campo name de cada elemento. Un campo es null, no aparece o es una lista vacía cuando no tenemos valor: nunca un marcador de posición.

Pruébelo sin código: el planificador del lado del sol ejecuta esta API en cualquier ruta o en su propio viaje y muestra el plano de asientos, el mapa, la cronología, las imágenes y el código de la llamada. Abrir el planificador →

Your route (POST)

Envíe su propia ruta como cuerpo JSON con POST a la misma URL. La respuesta tiene los mismos campos que GET más input (cómo se leyó su ruta), images (mapa de asientos, mapa de la ruta y cronología) y embed_html.

Las paradas sin geometría se unen con nuestro enrutador de carreteras; un tramo que no se puede calcular se dibuja como línea recta y se cuenta en input.legs_straight. Horas: al menos dos paradas con hora, o route.depart con route.duration_min o route.speed_kmh. Un viaje puede durar hasta 72 h.

Un campo erróneo o ausente devuelve HTTP 400 con error.field igual a su ruta, por ejemplo route.stops[2].lat o bus.seats.

curl -X POST "https://nakordoni.eu/api/v2/data/bus-sun-side" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "route": {
        "stops": [
            {
                "name": "Poznań Dworzec Autobusowy",
                "lat": 52.4011,
                "lon": 16.911,
                "dep": "08:00"
            },
            {
                "name": "Konin",
                "lat": 52.223,
                "lon": 18.2511,
                "arr": "09:20",
                "dep": "09:25"
            },
            {
                "name": "Łódź Kaliska",
                "lat": 51.7573,
                "lon": 19.4306,
                "arr": "10:55",
                "dep": "11:05"
            },
            {
                "name": "Warszawa Zachodnia",
                "lat": 52.219,
                "lon": 20.965,
                "arr": "13:10"
            }
        ],
        "date": "2026-06-21",
        "timezone": "Europe/Warsaw"
    },
    "bus": {
        "bus_model": "minibus"
    },
    "images": [
        "seat_map",
        "route_map",
        "timeline"
    ],
    "format": "png",
    "theme": "light",
    "lang": "en",
    "weather": true
}'

const res = await fetch('https://nakordoni.eu/api/v2/data/bus-sun-side', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer NKD-DEV-XXXX-XXXX-XXXX', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    route: { stops: [
      { name: 'Poznań', lat: 52.4011, lon: 16.911, dep: '08:00' },
      { name: 'Warszawa', lat: 52.219, lon: 20.965, arr: '11:30' } ],
      date: '2026-06-21', timezone: 'Europe/Warsaw' },
    bus: { bus_model: 'comfort_coach_2_1' },
    images: ['seat_map'], format: 'svg', lang: 'pl'
  })
});
const { data } = await res.json();
console.log(data.recommend.shade_side, data.recommend.best_shade_seats);
document.querySelector('#seats').innerHTML = data.embed_html;   // or <img src="data.images.seat_map.url">

Images and embed_html

Cada imagen tiene su propia URL con un nombre de archivo aleatorio (.png, .webp o .jpg). Las URL no necesitan clave y son válidas durante 12 horas (expires_at); copie los archivos si los necesita más tiempo. embed_html es un figure autónomo con el mapa de asientos como SVG inline y una línea de crédito de nakordoni.eu; conserve el crédito al mostrarlo.

Abajo: las imágenes del cuerpo de ejemplo anterior (minibús, de Poznań a Varsovia, 21 de junio).

Bus catalogue

bus_model acepta una de estas clases genéricas de vehículo (no marcas concretas). Cualquier campo de autobús que envíe sustituye al modelo; seats se convierte en rows según el layout. La misma lista está disponible en JSON desde bus-sun-catalog.

Allowed values: layout 2+2 | 2+1 | 1+2 · rows {"min":4,"max":20,"custom_min":8} · door_side right | left · windshield large | normal · rear_window none | small | large · window_height standard | panoramic · deck single | upper | lower · mid_door true | false

Weather

Con weather=1 (predeterminado; en un cuerpo POST "weather": true) la respuesta usa un pronóstico meteorológico por horas a lo largo del viaje para los próximos 3 días (72 h); las partes posteriores del viaje usan cielo despejado. summary.sun_*_min se ponderan entonces según el pronóstico, cada fila de timeline recibe wx {code, f, temp, precip} y weather {used, window_h, covered_pct, sunny_min, cloudy_min, rain_min, max_temp, note_key} indica qué parte del viaje cubrió el pronóstico. recommend_clear es la respuesta con cielo despejado; weather_changes_answer es true cuando el pronóstico cambia el lado de sombra. Cuando el pronóstico es sobre todo nuboso o lluvioso, recommend.reason_key es mostly_cloudy y shade_side es any. recommend.tip_key hot_sun_side significa que en el lado soleado se pronostican 28 °C o más.

Quota and accuracy

GET, y POST con "images": [], cuentan 1 unidad de la clase pesada; un POST que genera imágenes cuenta 2. bus-sun-catalog es una llamada barata. El mismo cuerpo POST devuelve la respuesta almacenada durante un máximo de 6 horas (1 hora si se usó un pronóstico meteorológico).

El resultado es una estimación a partir de la geometría de la ruta y la posición del sol. No conocemos cortinas, cristales tintados, edificios, árboles, relieve ni cambios de ruta. Las nubes y la lluvia proceden de un pronóstico meteorológico solo para viajes en los próximos 3 días; los viajes posteriores suponen cielo despejado. confidence es menor cuando el sol está bajo, el viaje es corto, la ruta gira a menudo o el pronóstico es sobre todo nuboso.

curl "https://nakordoni.eu/api/v2/data/bus-sun-side?route_id=521&dir=direct&date=2026-06-21&bus_model=standard_coach&lang=en" \
  -H "Authorization: Bearer NKD-DEV-XXXX-XXXX-XXXX"