API Bus Sun Side Online

Ce parte a autocarului primește soare sau umbră într-o călătorie și ce locuri sunt cele mai bune pentru umbră sau pentru priveliște. Călătoria este parcursă în pași de 5 minute: poziția și direcția din traseu, poziția soarelui în acel loc și la acea oră, apoi o estimare pe fiecare loc pentru dispunerea aleasă a autobuzului. Folosiți un traseu din registrul nostru de curse licențiate (route_id), două puncte (from/to) sau trimiteți prin POST propriul traseu (opriri sau un polyline) pentru a obține și o hartă a locurilor, o hartă a traseului și o cronologie ca imagini. Rezultatele sunt o estimare pe baza geometriei și a poziției soarelui; umbra reală depinde și de perdele, clădiri, relief și vreme.

GET https://nakordoni.eu/api/v2/data/bus-sun-side — clasă de cotă: heavy

Câmpurile răspunsului — în interiorul obiectului data din plicul răspunsului. [] marchează o listă, deci data.items[].name este câmpul name al fiecărui element. Un câmp este null, lipsește sau este o listă goală atunci când nu avem o valoare — niciodată un substitut.

Încercați fără cod: planificatorul părții însorite rulează acest API pe orice rută sau pe propria călătorie și arată harta locurilor, harta, cronologia, imaginile și codul apelului. Deschideți planificatorul →

Your route (POST)

Trimiteți propriul traseu ca un corp JSON prin POST la același URL. Răspunsul are aceleași câmpuri ca GET, plus input (cum a fost citit traseul), images (harta locurilor, harta traseului și cronologia) și embed_html.

Opririle fără geometrie sunt unite cu routerul nostru rutier; un segment care nu poate fi rutat este desenat ca linie dreaptă și numărat în input.legs_straight. Ore: cel puțin două opriri cu oră sau route.depart cu route.duration_min ori route.speed_kmh. O călătorie poate dura până la 72 h.

Un câmp greșit sau lipsă dă HTTP 400 cu error.field setat la calea lui, de exemplu route.stops[2].lat sau 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

Fiecare imagine are propriul URL cu un nume de fișier aleatoriu (.png, .webp sau .jpg). URL-urile nu necesită cheie și rămân valabile 12 ore (expires_at); copiați fișierele dacă aveți nevoie de ele mai mult timp. embed_html este un figure autonom cu harta locurilor ca SVG inline și o linie de atribuire nakordoni.eu; păstrați atribuirea când îl afișați.

Mai jos: imaginile pentru corpul de exemplu de mai sus (microbuz, Poznań – Varșovia, 21 iunie).

Bus catalogue

bus_model acceptă una dintre aceste clase generice de vehicule (nu mărci anume). Orice câmp de autobuz trimis suprascrie modelul; seats este transformat în rows pentru layout. Aceeași listă este disponibilă ca JSON din 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

Cu weather=1 (implicit; în corpul POST "weather": true) răspunsul folosește o prognoză meteo orară de-a lungul călătoriei pentru următoarele 3 zile (72 h); părțile ulterioare ale călătoriei folosesc cer senin. summary.sun_*_min sunt atunci ponderate după prognoză, fiecare rând din timeline primește wx {code, f, temp, precip}, iar weather {used, window_h, covered_pct, sunny_min, cloudy_min, rain_min, max_temp, note_key} arată cât din călătorie a acoperit prognoza. recommend_clear este răspunsul pentru cer senin; weather_changes_answer este true când prognoza schimbă partea cu umbră. Când prognoza indică mai ales nori sau ploaie, recommend.reason_key este mostly_cloudy, iar shade_side este any. recommend.tip_key hot_sun_side înseamnă că pentru partea însorită se prognozează 28 °C sau mai mult.

Quota and accuracy

GET, precum și POST cu "images": [], contează ca 1 unitate din clasa grea; un POST care generează imagini contează 2. bus-sun-catalog este un apel ieftin. Același corp POST returnează răspunsul stocat până la 6 ore (1 oră când s-a folosit o prognoză meteo).

Rezultatul este o estimare pe baza geometriei traseului și a poziției soarelui. Perdelele, geamurile fumurii, clădirile, copacii, relieful și un traseu modificat nu ne sunt cunoscute. Norii și ploaia provin dintr-o prognoză meteo doar pentru călătoriile din următoarele 3 zile; călătoriile ulterioare presupun cer senin. confidence este mai mic când soarele este jos, călătoria este scurtă, traseul cotește des sau prognoza este în mare parte noroasă.

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"