Bus Sun Side API Online

Which side of a coach gets the sun or the shade on a trip, and which seats are best for shade or for the view. The trip is walked in 5-minute steps: position and heading from the route, solar position at that place and time, then a per-seat estimate for the chosen bus layout. Use a route from our licensed-route registry (route_id), two points (from/to), or POST your own route (stops or a polyline) to also get a seat map, a route map and a timeline as images. Results are an estimate from geometry and solar position; real shade also depends on curtains, buildings, terrain and weather.

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

Response fields — inside the data object of the envelope. [] marks a list, so data.items[].name is the name field of each element. A field is null, absent or an empty list when we hold no value for it — never a placeholder.

Try it without code: the Bus Sun Side Planner runs this API on any route or your own trip and shows the seat map, map, timeline, images and the code for the call. Open the planner →

Your route (POST)

Send your own route as a JSON body with POST to the same URL. The answer has the same fields as GET plus input (how your route was read), images (seat map, route map and timeline) and embed_html.

Stops without a geometry are joined with our road router; a leg that cannot be routed is drawn as a straight line and counted in input.legs_straight. Times: at least two timed stops, or route.depart with route.duration_min or route.speed_kmh. A trip can be up to 72 h.

A wrong or missing field gives HTTP 400 with error.field set to its path, for example route.stops[2].lat or 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

Every image has its own URL with a random file name (.png, .webp or .jpg). The URLs need no key and stay valid for 12 hours (expires_at); copy the files if you need them longer. embed_html is a self-contained figure with the seat map as inline SVG and a nakordoni.eu credit line; keep the credit when you show it.

Below: the images for the example body above (minibus, Poznań to Warsaw, 21 June).

Bus catalogue

bus_model takes one of these generic vehicle classes (not specific makes). Any bus field you send overrides the model; seats is turned into rows for the layout. The same list is available as JSON from 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

With weather=1 (default; in a POST body "weather": true) the answer uses an hourly weather forecast along the trip for the next 3 days (72 h); later parts of the trip use a clear sky. summary.sun_*_min are then weighted by the forecast, each timeline row gets wx {code, f, temp, precip}, and weather {used, window_h, covered_pct, sunny_min, cloudy_min, rain_min, max_temp, note_key} tells how much of the trip the forecast covered. recommend_clear is the clear-sky answer; weather_changes_answer is true when the forecast changes the shade side. When the forecast is mostly cloud or rain, recommend.reason_key is mostly_cloudy and shade_side is any. recommend.tip_key hot_sun_side means that the sunny side is forecast at 28 °C or more.

Quota and accuracy

GET, and POST with "images": [], count 1 unit of the heavy class; a POST that makes images counts 2. bus-sun-catalog is a cheap call. The same POST body returns the stored answer for up to 6 hours (1 hour when a weather forecast was used).

The result is an estimate from the route geometry and the position of the sun. Curtains, tinted glass, buildings, trees, terrain and a changed route are not known to us. Clouds and rain come from a weather forecast for trips in the next 3 days only; later trips assume a clear sky. confidence is lower when the sun is low, the trip is short, the route turns often or the forecast is mostly cloudy.

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"