API Bus Sun Side Online

Quale lato di un pullman riceve il sole o l'ombra durante un viaggio, e quali posti sono i migliori per l'ombra o per la vista. Il viaggio viene percorso a passi di 5 minuti: posizione e direzione dal percorso, posizione del sole in quel luogo e in quell'ora, poi una stima per ogni posto per la disposizione di autobus scelta. Usa un percorso dal nostro registro delle linee autorizzate (route_id), due punti (from/to) o invia con POST il tuo percorso (fermate o polyline) per ottenere anche una mappa dei posti, una mappa del percorso e una timeline come immagini. I risultati sono una stima basata sulla geometria e sulla posizione del sole; l'ombra reale dipende anche da tende, edifici, terreno e meteo.

GET https://nakordoni.eu/api/v2/data/bus-sun-side — classe di quota: heavy

Campi della risposta — all’interno dell’oggetto data della busta. [] indica una lista, quindi data.items[].name è il campo name di ogni elemento. Un campo è null, assente o una lista vuota quando non abbiamo un valore — mai un segnaposto.

Provalo senza codice: il pianificatore del lato al sole esegue questa API su qualsiasi linea o sul tuo viaggio e mostra mappa dei posti, mappa, cronologia, immagini e il codice della chiamata. Apri il pianificatore →

Your route (POST)

Invia il tuo percorso come corpo JSON con POST allo stesso URL. La risposta ha gli stessi campi di GET più input (come è stato letto il percorso), images (mappa dei posti, mappa del percorso e timeline) ed embed_html.

Le fermate senza geometria vengono collegate dal nostro router stradale; una tratta che non può essere calcolata viene disegnata come linea retta e conteggiata in input.legs_straight. Orari: almeno due fermate con orario, oppure route.depart con route.duration_min o route.speed_kmh. Un viaggio può durare fino a 72 h.

Un campo errato o mancante restituisce HTTP 400 con error.field impostato sul suo percorso, per esempio 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

Ogni immagine ha il proprio URL con un nome file casuale (.png, .webp o .jpg). Gli URL non richiedono chiave e restano validi per 12 ore (expires_at); copia i file se ti servono più a lungo. embed_html è un figure autonomo con la mappa dei posti come SVG inline e una riga di credito nakordoni.eu; mantieni il credito quando lo mostri.

Sotto: le immagini per il corpo di esempio qui sopra (minibus, da Poznań a Varsavia, 21 giugno).

Bus catalogue

bus_model accetta una di queste classi di veicoli generiche (non marche specifiche). Ogni campo dell'autobus inviato sovrascrive il modello; seats viene convertito in rows in base al layout. Lo stesso elenco è disponibile in JSON da 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 (predefinito; in un corpo POST "weather": true) la risposta usa una previsione meteo oraria lungo il viaggio per i prossimi 3 giorni (72 h); le parti successive del viaggio usano cielo sereno. summary.sun_*_min sono quindi ponderati in base alla previsione, ogni riga di timeline riceve wx {code, f, temp, precip} e weather {used, window_h, covered_pct, sunny_min, cloudy_min, rain_min, max_temp, note_key} indica quanta parte del viaggio è stata coperta dalla previsione. recommend_clear è la risposta con cielo sereno; weather_changes_answer è true quando la previsione cambia il lato in ombra. Quando la previsione è per lo più nuvolosa o piovosa, recommend.reason_key è mostly_cloudy e shade_side è any. recommend.tip_key hot_sun_side significa che per il lato al sole sono previsti 28 °C o più.

Quota and accuracy

GET, e POST con "images": [], contano 1 unità della classe pesante; un POST che crea immagini conta 2. bus-sun-catalog è una chiamata economica. Lo stesso corpo POST restituisce la risposta memorizzata fino a 6 ore (1 ora se è stata usata una previsione meteo).

Il risultato è una stima basata sulla geometria del percorso e sulla posizione del sole. Tende, vetri oscurati, edifici, alberi, terreno e un percorso modificato non ci sono noti. Nuvole e pioggia provengono da una previsione meteo solo per i viaggi nei prossimi 3 giorni; i viaggi successivi presuppongono cielo sereno. confidence è più bassa quando il sole è basso, il viaggio è breve, il percorso svolta spesso o la previsione è per lo più nuvolosa.

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"