Historia zmian API

On Fuel Prices, updated_at and the response's own age_hours/stale flag were running on different clocks: updated_at moves only when a price actually changes, but staleness was computed as if it moved on every confirmation. 46.7% of the priced index showed age_hours ≤48 and stale:false while updated_at was in fact more than 48 hours old, 12,620 stations over a week old. Each price now also carries confirmed_at — the last time we confirmed the price, hour-floored, never earlier than updated_at — and age_hours/stale are computed from it. updated_at's meaning is unchanged: use it when you want to know when the price last moved, use confirmed_at when you want to know how current it is right now. Not present on the frozen v1 contract.

Two language bugs, both silent: sending the canonical grade code as lang=pl (or any of the other 24 site languages) got fuel_type_local back in English regardless — only 10 languages were ever checked against the label table, so anything outside that list fell through to the default UI vocabulary rather than the language you asked for. Separately, lang=tr (or several other valid codes) answered station listings in Ukrainian, because an internal default of uk fired whenever the requested language did not sit in that same 10-language list. Both are fixed: the language you send is now the language you get, across all 25.

Also: brand on Nearby Fuel Stations no longer returns the raw ingest sentinel OTHER for the ~330 stations where we do not know the brand — it is null, consistent with every other unknown field in the response.

Asystent AI dla granic (/api/v1/data/assistant) zwracał 503 internal_error — „Asystent tymczasowo niedostępny” — gdy ten sam klucz zadał to samo pytanie dwa razy w ciągu pięciu minut. Nic nie było niedostępne: w większości takich przypadków odpowiedź była już wyliczona i gotowa do zwrócenia. Teraz jest zwracana normalnie, z ok: true i HTTP 200.

Gdy powtórzenie trafia w momencie, w którym pierwsza odpowiedź jest jeszcze zapisywana, wywołanie zwraca teraz 429 z error.code równym duplicate_request zamiast 503, dzięki czemu polityka ponowień odróżni „zapytaj ponownie za chwilę” od rzeczywistej awarii. Oba przypadki były też liczone do wskaźnika błędów konta jako błędy serwera; już nie są. W samym żądaniu nic się nie zmienia — żadnego parametru, żadnej wersji. duplicate_request jest wymieniony wraz z pozostałymi kodami błędów w dokumentacji.

Parkingi dla ciężarówek (/api/v2/data/truck-parkings) zwracały wpisy z name równym null i pustym address — w okolicy Bensheim 20 z 50. To miejsca, które mamy wyłącznie jako współrzędną: nie ma czego wyświetlić ani z czym dopasować własnego zbioru POI. Nie należą już do tego produktu: zwraca on teraz tylko nazwane lokalizacje, obecnie ponad 22 000 w całej Europie. Jeśli sami odfiltrowywaliście wpisy bez nazwy, ten kod jest teraz zbędny, ale nieszkodliwy. Odpowiedzi dla tego samego radius i limit są krótsze, a każdy zwrócony wpis nadaje się do użycia.

Osobno: około 10 000 parkingów miało w polu name surową parę współrzędnych, na przykład 51.927301,10.14112, podczas gdy prawdziwa nazwa znajdowała się w address. Teraz mają tę nazwę — Ionity, Seesen, Rest Area A5 E35 Kaelberpfad, Bensheim — wszędzie tam, gdzie się pojawiają, także w /api/v1/data/pois. id każdego miejsca pozostaje bez zmian, więc zapisane przypisania są nadal poprawne; zmienia się tylko name.

snapshot.updated_at w /api/v1/data/queue i /api/v1/data/multi to czas lokalny w strefie samego przejścia granicznego (na przykład Europe/Istanbul, Europe/Sofia, Europe/Budapest, Europe/Warsaw, Europe/Kyiv), a do tej pory nic w odpowiedzi nie wskazywało, o którą strefę chodzi, więc klient nie mógł sprowadzić tej wartości do konkretnego momentu. snapshot zyskuje dodatkowe pole timezone (nazwa IANA) obok updated_at. Bez nowego parametru, bez nowej wersji, bez zmian w pozostałych polach.

Każdy paliwowy endpoint opisywał dotąd własne pokrycie listą pisaną ręcznie: AT, DE, DK, ES, FR, HR, IT, LU, PL, PT, SI, a Polska była w niej zawężona do obszaru Trójmiasta. Oba twierdzenia dawno się zdezaktualizowały. Pokrycie jest teraz mierzone z żywego indeksu stacji i przeliczane co sześć godzin: 39 krajów ma dziś stacje z cenami, a Polska wśród nich w całym kraju, nie w trzech miastach. W samym zapytaniu nie zmienia się nic: żaden parametr, żadna wersja.

Stacje paliw w pobliżu i Najtańsze paliwo: gdy wyszukiwanie nic nie zwraca, blok coverage zawiera teraz zmierzone station_countries, station_counts, sparse_coverage i measured_at, zawężone do gatunku paliwa, o który zapytano, a nie do paliwa w ogóle. Kraj trafia do sparse_coverage, gdy mamy w nim 25 stacji z cenami lub mniej — to wynik liczenia, nie ocena.

Pojawia się nowa uwaga dla gatunku, który rozpoznajemy, ale którego nikt nie wycenia tam, gdzie pytasz. Do tej pory coverage.fuel_type_note pojawiało się tylko wtedy, gdy sama nazwa z dystrybutora była nam nieznana. Teraz pojawia się także wtedy, gdy nazwa rozpoznaje się poprawnie, a w tym kraju po prostu nie ma dla niej żadnej ceny; wskazuje kraje, w których ten gatunek jest wyceniany, oraz gatunki, które wyceniamy w twojej okolicy. Czeska nazwa Natural 100 to czysty przykład: rozpoznaje się, a żadne źródło nie podaje dla niej ceny w Czechach. Pusta odpowiedź przestaje wyglądać jak zepsute zapytanie.

Gatunki paliwa (/api/v2/data/fuel-grades) zyskuje priced_countries i priced_station_counts dla każdego gatunku oraz priced_here, gdy podasz ?country=. Te listy znaczą co innego: kraj w countries to kraj, w którym akceptujemy taką nazwę z dystrybutora, a priced_countries to miejsca, gdzie źródło rzeczywiście podaje cenę, więc priced_here równe 0 to prawdziwa odpowiedź, a nie luka w odpowiedzi. Ładunek niesie też coverage_measured_at i coverage_note, a Cache-Control spada z 24 godzin do 6, by odpowiadać częstotliwości przeliczania.

Rozpoznawanych jest też więcej lokalnych nazw z dystrybutorów, wśród nich Klimadiesel 90 (HVO100) i HVO Diesel, Erdgas i Metano, Autogas i Autogaz, DEF dla AdBlue, a także szereg markowych nazw diesli i benzyn premium. Kolejność rozpoznawania nie zmieniła się, a dopasowanie pozostaje dokładne, więc żadna nazwa działająca wcześniej nie znaczy dziś czego innego, a nowa nazwa może co najwyżej zamienić pustą odpowiedź na odpowiedź z cenami. Równocześnie poprawiono dokumentację referencyjną i opisy endpointów we wszystkich 25 językach serwisu.

Najtańsze paliwo (/api/v2/data/fuel-cheapest) zwracało najbliższe stacje w kolejności odległości zamiast najtańszych. Ponieważ sortowanie było stosowane przed przycięciem wyniku do Twojego limit, najtańsze stacje w promieniu wyszukiwania mogły całkowicie nie pojawić się w odpowiedzi. Sortowanie znów działa poprawnie: najpierw najtańsza cena dla żądanego rodzaju paliwa, przy remisie wygrywa bliższa stacja, a stacja bez ceny dla danego rodzaju paliwa trafia na koniec. W samym żądaniu nic się nie zmienia — żadnego nowego parametru, żadnej nowej wersji.

Odpowiedzi paliwowe v2 są też udokumentowane zgodnie z tym, jak są faktycznie zwracane: stacje pojawiają się w data.stations[], po jednym wpisie na fizyczną stację, a każdy rodzaj paliwa jest zagnieżdżony w obiekcie prices (price, currency, local_name, updated_at, age_hours, stale) oraz station_ref, grades, total_found i notices. Dokumentacja dla Pobliskich stacji paliw i Najtańszego paliwa nadal opisywała starszą, płaską listę wierszy data.data[].

Na stronie płatności (zakładka miesięczna) dostępne są dwa dodatki do dowolnego planu, bez jego zmiany: Dodatkowe zapytania prognoz — +100 zapytań prognoz i statystyk dziennie na blok, 2 € miesięcznie za blok, do 10 bloków; oraz Dodatkowe kraje — +1 kraj do zadeklarowania na sztukę, 2 € miesięcznie za każdy. Zmiana ilości pokazuje dokładną wycenę proporcjonalną, zanim cokolwiek zostanie obciążone.

Od 10 listopada 2026 każdy plan zawiera określoną liczbę zadeklarowanych krajów: Explorer i Student 4, Starter 10, Pro i wyżej bez ograniczeń. Od tej daty deklaracji dłuższej niż plan plus zakupione dodatkowe kraje nie da się zapisać; zakładka Konto pokazuje już Twój limit, a konta, które go przekraczają, widzą podpowiedź na pulpicie. Przed 10 listopada nic się nie zmienia.

Piaskownica API oznacza teraz każdy endpoint na liście jego klasą limitu (Ciężki / Standardowy), pokazuje koszt limitu dla wybranej wersji, zanim cokolwiek uruchomisz, a po wywołaniu pokazuje, ile to samo wywołanie kosztowałoby z Twojego produkcyjnego limitu — łącznie ze wzorem ceil(N ppids × M sub-products / 2) stosowanym do wywołań w formie /multi.

To podgląd tylko do odczytu: same wywołania w piaskownicy pobierane są z osobnego budżetu testowego piaskownicy, nigdy z Twojego produkcyjnego limitu.

Od dziś wszystko, co publicznie ogłosiliśmy jako wycofywane, jest zamknięte dla kont deweloperskich utworzonych w dniu ogłoszenia lub później. Jeśli Twoje konto istniało przed ogłoszeniem, nic się nie zmienia — zachowujesz pełny okres przejściowy, aż do daty wycofania podanej we wpisie, który je ogłosił.

Dlaczego ta zasada istnieje. 24 sierpnia 2026 ogłosiliśmy, że truck-bans v1 zostaje wycofane 8 września 2026. Dwa konta zarejestrowały się kilka dni po tym ogłoszeniu, zbudowały integrację na v1 i dzieliły je godziny od 410, choć nie dotarł do nich żaden nasz e-mail: zarówno ogłoszenie, jak i partia powiadomień poprzedzały ich rejestrację. Nic w API nie powstrzymało ich przed sięgnięciem po wersję, o której już powiedzieliśmy, że znika. To był nasz błąd, a to jest jego naprawa — nie możesz od nowa sięgnąć po coś, co jest już zaplanowane do usunięcia.

Jak to wygląda. Takie wywołanie jest odrzucane z 410 Gone i kodem błędu version_closed_to_new_accounts. Komunikat podaje datę wycofania, datę ogłoszenia i wersję, której należy użyć zamiast niej. To celowo inny kod niż version_sunset, który dostaje każde konto po nadejściu samej daty wycofania — wsparcie odróżni „przyszedłeś za późno, by zacząć” od „to zniknęło dla wszystkich” bez czytania logów.

O prawach nabytych decyduje data utworzenia konta, a nie pierwsze wywołanie. Jeśli zarejestrowałeś się przed ogłoszeniem, a integrację zaczynasz dopiero teraz, nadal masz pełny okres przejściowy: mogłeś budować na tej wersji od dawna.

Obowiązuje już teraz dla truck-bans v1 (ogłoszone 24 sierpnia 2026, wycofanie 8 września 2026) i automatycznie dla każdego wycofania, które ogłosimy od tej pory. Nic nowego nie jest od Ciebie wymagane: każda odpowiedź na wycofywanej wersji już niesie nagłówki Deprecation, Sunset i Link: rel="successor-version", więc nowa integracja zobaczy nadchodzące wycofanie bez czytania tej strony.

Ciąg dalszy wczorajszej zmiany w v4 (zgłoszenie deweloperskie #105). Listy destination rozdzielane przecinkami w v1 i v2 nadal działają, ale podlegają teraz temu samemu terminowi co destination=all: oba przestają działać 2026-10-06 (do tego czasu nagłówki Deprecation/Sunset, potem 400 destination_list_removed ze wskazaniem /api/v4/ jako zamiennika). Istniejące ograniczenie do 10 elementów na listach z przecinkami pozostaje przed tą datą bez zmian.

v4 nadal przyjmuje jeden cel na wywołanie — to się dzisiaj nie zmieniło. Zmieniło się tylko to, jak komunikujemy v1/v2: błąd 400 dla destination=all nie proponuje już listy z przecinkami jako drogi migracji (i tak wygasłaby tego samego dnia), tylko od razu wskazuje v4.

Poprawka w dokumentacji: przykład v4 na tej stronie brzmiał wcześniej /api/v4/data/border/1/2,3,4/9 — to lista z przecinkami, którą v4 odrzuca. Teraz jest to /api/v4/data/border/1/2/9. Kto skopiował stary przykład, dostałby 400 przy pierwszym wywołaniu; przepraszamy.

Nowy przetłumaczony klucz product_border_v4_p_destination trafia do wszystkich 25 języków serwisu i wprost opisuje zasadę jednego celu w v4, zamiast sięgać po sformułowanie z v1/v2.

/api/v4/data/border/{origin}/{destination}/{crossing_type} działa od dziś. Względem v2 zmieniają się trzy rzeczy i to one razem sprawiają, że jest to nowa wersja, a nie poprawka.

1. Koniec z destination=all. Nasze dane są licencjonowane osobno dla każdego kraju (Developer API Terms, sekcja 7), a symbol wieloznaczny rozwijany do „każdego sąsiada, dla którego mamy dane” zwraca kraje, do których Twoje konto może nie mieć uprawnień — i nic w samym żądaniu tego nie pokazuje. W v4 kraj wskazujesz sam.

2. Jeden kraj docelowy na wywołanie. /api/v4/data/border/1/2/9 pyta o jedną granicę. Listy po przecinku nie są przyjmowane: wyślij 1/2/9, 1/3/9 i 1/4/9 jako osobne wywołania. Lista po przecinku albo all dostaje w odpowiedzi 400 wraz z dokładnymi wywołaniami do wysłania, więc nic nie zawodzi po cichu.

3. Jeden kod dla ciężarówek. v1 i v2 dzieliły transport towarowy na 8 (Freight Transport) i 9 (Freight Transport up to 7.5 t). Na samym przejściu ten podział jest realny, ale żaden integrator nie może się na nim oprzeć: zapytanie o 9 w v2 na granicy UA-PL zwracało 21 z 70 przejść towarowych i nic tego nie sygnalizowało. v4 na 9 odpowiada wszystkimi pasami dla ciężarówek, a 8 przyjmuje jako alias 9. Każdy wiersz niesie własny crossing_type, więc połączoną odpowiedź nadal da się rozłożyć.

W v1 i v2 destination=all działa do 2026-10-06 i do tego czasu zwraca nagłówki Deprecation / Sunset. Od tej daty te wersje również odpowiadają 400 na all — reszta v1 i v2 pozostaje nietknięta i dostępna. Ta sama data dotyczy pozostałych skrótów „wszystkie kraje”: travel-matrix bez ?dest=, bus-carriers z ?ppid=all oraz fuel-grades bez ?country=.

v3, ogłoszoną dziś wcześniej, zastępuje v4. v3 różniła się od v4 tylko tym, że wciąż przyjmowała listę po przecinku, a żadna integracja tej formy nie używa. Adresy v3 nadal odpowiadają, więc nic napisanego pod nie się nie zepsuje, ale v3 nie jest dokumentowana i nie będzie dalej rozwijana — przejdź na v4.

Cała reszta v4 jest jak w v2: kierunkowa kolejność segmentów ścieżki, direction{from,to}, stale i ?max_age_min=.

Numeryczne identyfikatory w /border/{origin}/{destination}/{crossing_type} nigdy nie zostały opublikowane w formie tabeli, więc integratorzy odtwarzali je ze stref czasowych i przykładowych adresów. Teraz są w dokumentacji, w sekcji Country and vehicle-type codes, generowanej z tych samych tabel, względem których API waliduje żądania — identyfikatory krajów wraz z granicami, do których każdy się rozwija, i każdy crossing_type z etykietą zwracaną przez API.

Publikując je, znaleźliśmy w piaskownicy i w metadanych endpointów opis 8 jako „truck<7.5t” i 9 jako „truck”. Jest odwrotnie: API oznacza 8 jako Freight Transport, a 9 jako Freight Transport up to 7.5 tons, i tak było zawsze. Jeśli wybierałeś kod ciężarówki z podpowiedzi parametru, filtrowałeś pas przeciwny do zamierzonego. Poprawione wszędzie, a v3 usuwa ten wybór całkowicie.

API Terms v1.1 zastępują v1.0 jeszcze przed jej wejściem w życie i obowiązują od 2026-10-06. Zaakceptuj je w swoim panelu.

Sekcja 7 mówi teraz, czym jest Rynek: to kraj, którego dane wykorzystujesz — ten, w którym leży żądane przejście lub granica — a nie kraj, w którym mieszkają Twoi użytkownicy. Nasz panel w różnych miejscach podawał obie wersje; egzekwowana była zawsze pierwsza.

Dwie zmiany na Twoją korzyść. Kraje już zatwierdzone dla Twojego konta pozostają dostępne, gdy późniejsza zmiana jest w trakcie rozpatrywania (dodanie kraju nie zawiesza już tych, które masz). A jeśli nie odpowiemy na deklarację rynku w ciągu 5 dni roboczych, do czasu odpowiedzi obowiązują pełne limity Twojego planu.

Sekcja 10.3 odpowiada teraz temu, o co faktycznie prosi panel, a sekcja 13.2 określa podstawę dostępności, którą mierzymy i możemy Ci pokazać.

Trzy produkty niosą teraz dodatkowe pole data_quality (high albo low), które oznacza, czy odczyt jest rzeczywistą obserwacją, czy oszacowaniem modelu przy braku źródła zliczania na żywo na danym przejściu: queue (na najwyższym poziomie w snapshot i w każdym wierszu historycznym w data[] — brak go w wierszach prognozy), update-info (w kopercie) oraz multi (w obu podobiektach, queue i update_info, dla każdego przejścia). To nie jest nowy sygnał — flaga istniała już wewnętrznie — ale nigdy nie była wystawiana, więc przejście w pełni modelowane wyglądało identycznie jak zmierzone bezpośrednio. is_realtime celowo pozostaje bez zmian: dla wierszy modelowanych nadal ma wartość true, a zmiana tego znaczenia byłaby łamiącą zmianą poziomu v2, której tu nie wprowadzamy.

Również w tym wydaniu: produkt queue-advanced nie redystrybuuje już surowych danych pogodowych od dostawcy. weather_main, temperature i wind_speed zastąpiono pochodnymi condition_code (skala zagrożenia 0–5, null, gdy brak danych pogodowych), condition i severity.

Od 2026-08-30 jedno żądanie /api/v1/data/multi jest obsługiwane dla maksymalnie 5 przejść granicznych. Wywołanie zawierające więcej identyfikatorów PPID nie jest odrzucane: nadal zwraca 200, ale odpowiedź obejmuje tylko pierwsze 5 identyfikatorów w ?ppids=. Pozostałe identyfikatory są pomijane, zwracane w meta.ppid_cap.ignored i nie obciążają Twojego limitu — opłata naliczana jest za to, co wywołanie faktycznie zwróciło.

Dopóki wywołanie przekracza limit, odpowiedź zawiera nagłówek X-Devapi-Warning: multi_ppid_cap oraz blok meta.ppid_cap z polami cap, enforced_from, enforced, ppids_asked, ppids_answered i ignored[]. Do 2026-08-30 pola te pojawiają się z wartością enforced: false i pełnym zestawem wyników, więc nadchodzącą zmianę zobaczysz we własnych logach.

Zniżka na limit w wysokości połowy pozostaje bez zmian. Podziel swoje przejścia graniczne na grupy po 5 i wysyłaj jedno wywołanie na grupę w normalnym cyklu odświeżania; przy częstym odpytywaniu wyłącznie o długość kolejki i świeżość danych tańszym produktem klasy standardowej pozostaje update-info.

Wyliczany ukraiński zakaz upalny — zwracany przez include_ua_heat, a dla country=UA automatycznie — odpowiada teraz na zakres dat, o który pytasz. Wcześniej zwracał najbliższe siedem dni niezależnie od date_from i date_to, więc dla grudniowego okna po cichu wracały wiersze z bieżącego tygodnia. Zakaz jest wyliczany z prognozy pogody, a nie odczytywany z kalendarza zakazów, ma więc dwie granice, których kalendarz nie ma: nie sięga wstecz i kończy się tam, gdzie kończy się prognoza. Twój zakres jest teraz przecinany z tym, co prognoza faktycznie obejmuje, a nowe pole ua_heat_ban.forecast_horizon podaje ostatnią dostępną datę. Zakres poza tym horyzontem nie zwraca żadnych wierszy i wyjaśnia dlaczego w summary — to nie to samo co „brak zakazu”. Odpowiedzi v1 pozostają bez zmian.

Kształt odpowiedzi nie był dotąd nigdzie opisany — jedynym sposobem, by poznać zwracane dane, było wywołanie produktu. Teraz na stronie każdego produktu, pod tabelą parametrów, znajduje się tabela Pola odpowiedzi z krótkim opisem każdego pola; pola elementów listy pokazujemy jako items[].name, a pola poziomu koperty (usage, meta, snapshot, resolved_location) bez przedrostka. Opisane jest 40 z 42 produktów: dwa jeszcze nieuruchomione (weather, road-quality) celowo pozostają bez opisu. Ta sama tabela trafia do naszego publicznego repozytorium dokumentacji na GitHubie.

Każdy produkt paliwowy przyjmuje teraz lokalną nazwę rodzaju paliwa, a nie tylko nasz wewnętrzny zapis: ON w Polsce, Nafta w Czechach, Gázolaj na Węgrzech, Motorină w Rumunii, ДП na Ukrainie, Motorin w Turcji, Gasóleo w Portugalii i Hiszpanii. Nazwa rozpoznawana jest najpierw według kraju — „95” to E10 na duńskim dystrybutorze i E5 na polskim — więc wyślij country razem z lokalną nazwą albo współrzędne, po których da się umiejscowić punkt. W odpowiedzi wracają fuel_type (kanoniczne), fuel_type_requested (dokładnie jak wpisano) i fuel_type_local. Nazwy, której nie potrafimy umiejscowić, nigdy nie zamieniamy na domyślny rodzaj paliwa: odpowiedź wraca pusta i wprost to mówi.

Cała tablica jest teraz osobnym produktem — GET /api/v2/data/fuel-grades[?country=PL][&fuel_type=ON] — nasze kanoniczne rodzaje paliwa i ich lokalne nazwy w 41 krajach Europy, także na rynkach, dla których nie podajemy cen. Poziom krajowy i regionalny produktów fuel oraz fuel-local dostał też obiekt grades wiążący każdy klucz ceny z rodzajem paliwa i jego nazwą na stacji.

Produkt truck-bans odpowiada teraz na zapytanie o konkretną datę lub zakres dat pod adresem /api/v2/data/truck-bans. Do tej pory zawsze zwracał najbliższe 7 dni i ignorował przesłaną datę, więc zbudowanie kalendarza wymagało jednego zapytania na każdy dzień — a w planie z dwoma zapytaniami na sekundę większość z nich jest odrzucana z 429 qps_exceeded.

Użyj ?date=YYYY-MM-DD dla jednego dnia albo ?date_from= oraz ?date_to= dla zakresu. Obie granice są włączne i każdą można pominąć: początek domyślnie to dzisiaj, koniec to początek plus 7 dni. Okno może obejmować najwyżej 92 dni — dłuższe zostaje odrzucone z 400 date_range_too_long, zamiast po cichu przyciąć wynik. To kalendarz nastawiony na przyszłość: okno może zaczynać się najwyżej 7 dni wstecz, a starsze daty są odrzucane, a nie zwracane — zasięg sięga naprzód do 31 grudnia 2028 w 23 krajach.

Każda odpowiedź zawiera teraz obiekt window wskazujący dokładny zakres, który obejmuje. Jest to pole dodatkowe, wysyłane również w v1, przy czym v1 zachowuje swoje niezmienione 7-dniowe okno. Uwaga: include_ua_heat zawsze obejmuje najbliższe 7 dni, niezależnie od tego, o jakie okno prosisz — jest wyliczany z prognozy pogody, a nie z kalendarza zakazów. Przypominamy, że v1 tego produktu zostaje wycofana 8 września 2026.

Dwa powiązane usprawnienia w całym API: każdy parametr, którego produkt nie akceptuje, jest teraz wymieniony w polu ignored_params w odpowiedzi, zamiast być po cichu odrzucany, a błędy walidacji z serwisu danych docierają do Ciebie w oryginalnym brzmieniu, z kodem maszynowym w error.reason.

Trzy poprawki jakości odpowiedzi wynikające z audytu bramy API (zgłoszenie #43).

Nagłówek X-API-Key jest teraz akceptowany obok Authorization: Bearer i ?key=. Jeśli Twój klient HTTP wysyła klucze w nagłówku o nazwie X-API-Key, teraz to działa — wcześniej był on po cichu ignorowany, a wywołanie odrzucane jako missing_api_key. Authorization: Bearer pozostaje udokumentowaną, zalecaną formą.

Komunikat o braku klucza wymienia teraz wszystkie trzy sposoby uwierzytelniania (nagłówek Bearer, nagłówek X-API-Key lub ?key=) zamiast samego odnośnika do strony rejestracji.

Katalog checkpoints zawiera teraz has_day_stats w każdym wierszu — dodatkową wartość logiczną informującą, czy API „Najlepszy czas na przekroczenie” (day-stats) ma dane dla danego przejścia. Day-stats istnieje tylko dla części monitorowanych przejść; sprawdzaj tę flagę przed odpytywaniem, aby uniknąć przewidywalnych 404. Istniejące pola pozostają bez zmian.

Poprawione też w dokumentacji: produkt road-conditions zawsze uwzględniał parametr lang do lokalizacji etykiet — po prostu nie był on wymieniony.

Dwie poprawki i jedna nowa wersja produktu truck-bans.

Kraje rozdzielone przecinkiem już działają. ?country= przyjmuje listę do 3 kodów ISO-2, na przykład ?country=DE,RO. Dłuższa lista jest odrzucana z 400 too_many_countries, a nie po cichu przycinana — to kalendarz zakazów dla pojedynczego kraju, a nie kanał zbiorczy. Wcześniej to nie działało: separator był usuwany, więc DE,RO odczytywano jako pojedynczy token DERO, który nic nie dopasowywał i zwracał success: true z total_bans: 0 — pewne „brak zakazów” dla dwóch krajów, które łącznie miały ich 22. Jeśli obchodziłeś to, wysyłając osobne żądanie na każdy kraj, teraz jedno żądanie obejmuje wszystkie i kosztuje jedno wywołanie zamiast kilku.

Odpowiedzi informują teraz o własnej kompletności. Trzy dodatkowe pola — returned, total_available i truncated — mówią, czy odpowiedź została obcięta. Zwłaszcza żądanie bez zawężenia do kraju zwraca przyciętą część, a dotąd nic w treści odpowiedzi tego nie sygnalizowało. total_bans zachowuje dotychczasowe znaczenie (wiersze w tej odpowiedzi), więc nic, co już parsujesz, się nie zmienia.

v2 jest zawężona do jednego kraju. W /api/v2/data/truck-bans parametr ?country= jest wymagany, a żądanie bez zawężenia jest odrzucane z 400 scope_required — ten produkt to kalendarz zakazów dla pojedynczego kraju, a nie kanał zbiorczy. v1 pozostaje dziś bez zmian — nadal przyjmuje żądanie bez zawężenia i nadal zwraca te same przycięte 50 wierszy co zawsze, więc nic z tego, co masz uruchomione, teraz się nie psuje. v1 tego produktu zostaje wycofana 8 września 2026 r. Działa normalnie do 7 września włącznie; od 8 września żądanie do v1 jest odrzucane z 410 Gone i komunikatem wskazującym v2. Do tego czasu każda odpowiedź v1 zawiera Deprecation: true, nagłówek Sunset z tą datą oraz nagłówek Link wskazujący wersję następczą, dzięki czemu biblioteka kliencka może pokazać termin bez czytania tej strony. Aby przeprowadzić migrację: zmień segment wersji na /api/v2/data/truck-bans i przekaż ?country=.

Jedna korekta dokumentacji: parametr date został usunięty. Był wymieniany od dawna, ale serwis nigdy go nie odczytywał, więc każde żądanie, które go wysyłało, po cichu dostawało domyślne okno 7 dni zamiast wskazanego dnia. Aby wybrać dzień, filtruj tablicę upcoming_bans po jej polu date. Kod ISO-3, taki jak DEU, również nie jest już zamieniany na nazwę kraju w podsumowaniu, gdzie dawał mylące „No truck ban data for: Germany.”

Produkt truck-bans zwraca teraz krajowe ograniczenia ruchu dla pięciu kolejnych państw: Belgii (BE), Białorusi (BY), Czarnogóry (ME), Macedonii Północnej (MK) i Szwecji (SE). Dotychczasowy zasięg dla Bułgarii, Grecji i Portugalii został rozszerzony i odświeżony — greckie ograniczenia sięgają teraz września 2027 roku, a Portugalia znów ma dane.

Kształt odpowiedzi się nie zmienił. Nowe wiersze mają te same klucze co każdy inny zakaz: date, time_from, time_until, restriction_type, restriction_details, min_weight_tons i details_url. Jeśli ograniczenie obowiązuje tylko pod pewnym warunkiem — na przykład białoruskie zakazy letnie obowiązują powyżej 25 °C — warunek ten jest podany w restriction_details, więc przeczytaj to pole, zanim ostrzeżesz kierowcę. min_weight_tons ma wartość null, gdy przepis dotyczy klasy transportu (towary niebezpieczne), a nie tonażu.

Produkty fuel-stations i fuel-cheapest zwracają teraz ceny z poszczególnych stacji w Polsce. Zasięg jest częściowy — obszar Trójmiasta (Gdańsk, Gdynia, Sopot) — dlatego Polska jest wskazana w nowej, dodatkowej tablicy coverage.sparse_coverage obok istniejącej listy coverage.station_countries. Kraj wymieniony w sparse_coverage ma dane stacyjne tylko dla części swojego terytorium; zapytanie w innym miejscu tego kraju zwraca pustą listę wraz z notatką o zasięgu, dokładnie jak dotąd. Polskie ceny podawane są w PLN.

Komunikat błędu zapytania zbiorczego również jest jaśniejszy: gdy brakuje lat, komunikat scope_required wskazuje teraz produkt fuel (?country=XX) dla średnich cen krajowych.

GET /api/v2/data/fuel-local?lat=&lon= rozstrzyga teraz cenę na trzech poziomach zamiast dwóch: station, następnie region, następnie country. Nowy poziom pośredni istnieje dla Ukrainy, gdzie ceny pojedynczych stacji nie istnieją nigdzie: punkt na Ukrainie otrzymuje teraz średnią dla swojego obwodu zamiast średniej krajowej, a do średniej krajowej wraca tylko wtedy, gdy dla obwodu nie ma notowań.

Odpowiedź z poziomu region zawiera kod obwodu (wartość ISO 3166-2, na przykład UA-46), region_name i region_center_dist_km oraz te same klucze cenowe co poziom kraju. Nadal rozgałęziaj kod według resolution, nigdy według kształtu odpowiedzi; odpowiedzi station i country pozostają bez zmian.

Nowy endpoint GET /api/v2/data/fuel-local?lat=&lon= zwraca najlepszą dostępną cenę paliwa dla dowolnego punktu w Europie. Tam, gdzie mamy dane stacyjne, odpowiada cenami najbliższych stacji, a poza tym średnią krajową kraju, w którym leży punkt — w tym Ukrainy, gdzie ceny pojedynczych stacji nie istnieją nigdzie.

Każda odpowiedź zawiera pole resolution wskazujące poziom, który odpowiedział: station (lista stacji z distance_km, każda we własnej walucie) albo country (jeden obiekt ze średnimi krajowymi). Rozgałęziaj kod według resolution, nigdy według kształtu odpowiedzi. Dostępne od /api/v2/; fuel, fuel-stations i fuel-cheapest pozostają bez zmian.

Produkty fuel-stations i fuel-cheapest obejmują teraz znacznie więcej stacji w Niemczech, a ceny są odświeżane przez cały dzień — także na terenach wiejskich. Parametr fuel_type przyjmuje 13 rodzajów paliwa: diesel, e5, e10, superplus, super100, premdiesel, truckdiesel, hvo, lpg, cng, adblue, e85 i lng. Gdy żadna stacja nie pasuje do zapytania, odpowiedź zawiera obiekt coverage z listą krajów, dla których dostępne są dane o stacjach.

Parametr radius= jest teraz akceptowany jako zgodny alias dla radius_km w każdym produkcie, który go dokumentuje. Produkty fuel-stations i fuel-cheapest zwracają dodatkowy obiekt coverage (lista krajów ze stacjami wraz z notatką) zamiast po cichu pustego wyniku, gdy żadna stacja nie pasuje. Obiekty przejść granicznych w route-plan zawierają teraz dodatkowy klucz wait_basis (car_lane lub vehicle_lane), dzięki czemu klient wie, kiedy dane o czasie oczekiwania dla ciężarówek pochodzą z pasa dla samochodów osobowych. Dopasowywanie przejść dla ciężarówek wzdłuż trasy jest znacznie dokładniejsze: awaryjne dane z pasa osobowego dla par przejść bez danych o pasie towarowym, zabezpieczenie przed błędnym kierunkiem, ostrzejszy próg odległości oraz usuwanie duplikatów przejść w tym samym miejscu. Wszystkie zmiany są addytywne, bez zmian łamiących zgodność.

Strona docelowa dla deweloperów ma teraz sekcje z kotwicami (#products, #plans, #quickstart, #integrations, #datasets, #apps, #companies, #showcase) oraz nawigację skokową, a każda karta produktu prowadzi do własnej strony dokumentacji. Nowa sekcja Mobile apps prezentuje Kordon Online i Truck Bans z linkami do Google Play. Uzupełnienie tłumaczeń: historia płatności, błędy logowania, linki do środowiska testowego i przycisk wyboru planu są teraz zlokalizowane we wszystkich 25 językach.

Odpowiedź beacona floty (POST /api/v1/fleet_position.php) zawiera teraz tablicę messages dostarczającą oczekujące wiadomości od właściciela do kierowcy. Nowy strumień JSON na żywo tylko dla właściciela (?ajax=live) oraz karta „Wiadomości do kierowców” na panelu floty. Nowa strona zaproszenia kierowcy /{lang}/get-nakbus (25 języków).

Zlokalizowano tytuł, opis i parametry product_fleet_vehicles/live/history oraz parametry historii floty we wszystkich 25 językach portalu deweloperskiego.

/api/v1/data/truck-bans zwraca teraz ten sam zestaw pól najwyższego poziomu niezależnie od tego, jakie zapytanie wywołało odpowiedź. Wcześniej zapytanie dotyczące kraju bez zakazów kalendarzowych, nierozpoznany ppid lub zwykłe dopasowanie w bazie danych mogły pomijać różne pola (np. country, covered_countries, ppid). Teraz każda odpowiedź konsekwentnie zawiera as_of, bans_by_country, countries_not_covered, country, covered_countries, current_bans, is_ban_active, lang, page_url, ppid, relevant_countries, source, success, summary, total_bans i upcoming_bans (null lub puste, jeśli nie dotyczy), co upraszcza analizę danych po stronie klienta.

Dziewięć nowych produktów dla poszczególnych usług. Te lokalizacyjne przyjmują lat/lon lub city + country (miasto geokodujemy za Ciebie): /api/v2/data/truck-parkings, /api/v2/data/shops, /api/v2/data/showers, /api/v2/data/restaurants, /api/v2/data/industrial, /api/v2/data/fuel-stations, /api/v2/data/fuel-cheapest (stacje uszeregowane według ceny dla danego typu paliwa) oraz /api/v2/data/internet-points; wyniki zawierają distance_km i są ograniczone przez radius. /api/v2/data/vignettes odpowiada, czy dany kraj wymaga winiety, wraz z aktualnymi cenami. Istniejący produkt pois obsługuje teraz lon i radius zgodnie z dokumentacją, a tryb mode=nearest produktu fuel również przyjmuje lon. Wszystkie dziewięć jest dostępnych w piaskownicy.

Każdy zakaz w /api/v1/data/truck-bans zawiera teraz restriction_type (General / Local / Sunday / Holiday / Seasonal), restriction_details (dokładny zakres lub drogi, których dotyczy) oraz min_weight_tons. details_url prowadzi teraz do stron dla poszczególnych krajów na nakordoni.eu. Nowy opcjonalny parametr lang wybiera język nazw krajów i podsumowania; domyślnie jest to teraz angielski.

Nieprawidłowy ?ppid= zwraca teraz prawdziwą przyczynę zamiast lakonicznego "Request failed": błąd wskazuje parametr, oczekiwany format id_<number> oraz kieruje do /api/v1/data/checkpoints. Tabele parametrów dla stats, forecast, update-info, weather i bus-carriers pokazują teraz przykład id_13 we wszystkich 25 językach.

Przeprojektowana powłoka portalu (górny pasek, boczne menu z ikonami, pulpit KPI, układy kartowe) jest teraz domyślna dla wszystkich zalogowanych kont deweloperskich — wcześniej niż planowane wdrożenie 10 sierpnia. Aby w dowolnym momencie wrócić do klasycznego układu, użyj ?v=1 , aby w każdej chwili wrócić do klasycznego układu.

Wszystkie strony portalu dewelopera — strona główna, dokumentacja, pulpit, AI Studio, piaskownica, zgłoszenia, wnioski, eksport, flota, aktualności, dziennik zmian i strony konta — nie ładują już żadnych skryptów ani miejsc reklamowych. Dotyczy to całego portalu, a nie tylko logowania i rejestracji jak wcześniej.

Zaplanuj całą podróż przez granicę jednym zapytaniem: /api/v2/data/route-plan zwraca trasę, przejścia graniczne rzeczywiście na niej leżące wraz z bieżącą kolejką lub prognozą na godzinę Twojego przyjazdu oraz postoje, które kierowca naprawdę robi — przerwy na odpoczynek, posiłek i tankowanie — na jednej osi czasu.

Granica jest częścią tej osi. Długa kolejka liczy się jako przerwa, która i tak była należna, i zeruje licznik czasu jazdy, więc trzygodzinne oczekiwanie nigdy nie jest podawane jako trzy godziny plus pełny zestaw przerw, których nikt nie zrobił. Samochody osobowe mają model higieny jazdy; autobusy i ciężarówki obowiązkowy odpoczynek wg UE 561/2006, a narzut serwisowy autobusów skalibrowano na ponad 1000 licencjonowanych rozkładów międzynarodowych. Dodaj stop_places=1, aby nazwać prawdziwy parking lub stację paliw przy każdym postoju, oraz via=lat,lon, aby poprowadzić trasę przez inne przejście.

Nowość w menu portalu: Prezentacja — żywa, zawsze aktualna prezentacja platformy danych nakordoni dopasowana do Twojego rynku (ubezpieczenia, turystyka, logistyka, przewoźnicy, media, nawigacja, paliwo, fintech, sektor publiczny lub projekty własne). Pokazuje rzeczywiste wolumeny platformy z 30 dni, Twoje własne użycie API, statystyki czasu odpowiedzi i limitów oraz rekomendację planu, gdy Twoje wywołania sięgają granic darmowego progu. Wybierz lub potwierdź swój rynek (lub rynki) na stronie, w profilu — albo podczas rejestracji. Otwiera się automatycznie przy pierwszej wizycie; automatyczne otwieranie możesz wyłączyć na samej stronie.

Jeśli asystent ma włączony kanał, ale wywołanie nie niesie kontekstu, którego ten kanał potrzebuje — na przykład queue bez ppid— kanał jest teraz pomijany jeszcze przed wysłaniem jakiegokolwiek zapytania i nie jest naliczany. Wcześniej był wywoływany mimo to, kończył się błędem i i tak kosztował jednostkę. Studio pokazuje, czego potrzebuje każdy kanał, przelicza cenę w miarę uzupełniania kontekstu i oznacza wyniki jako ✓ wykonany / ⊘ pominięty, bez opłaty / ✕ błąd; API zwraca data.feeds_skipped , które dokładnie wskazuje, jaki parametr przekazać.

Odpowiedzi nie wspominają już o kanałach, źródłach danych ani o niczym technicznym: brakujący kanał to co najwyżej jedno zwykłe zdanie dla użytkownika końcowego, nigdy nazwa wewnętrzna. Kanały mające wyłącznie filtry opcjonalne (na przykład fuel zawężony do kraju, dla którego nie mamy danych) wracają teraz do szerokiego zbioru danych, zamiast nie zwracać nic.

Nowość: /{lang}/developers/studio. Zbuduj asystenta AI, który odpowiada na podstawie Twoich treści i naszych danych granicznych na żywo. Przekaż nam swój markdown albo po prostu wskaż strony, a my je pobierzemy i zaindeksujemy — utrzymujesz wyłącznie własne pliki. Wybierz, których naszych kanałów może używać (kolejka, prognoza, alternatywy, statystyki dobowe, paliwo, zakazy dla ciężarówek, niedziele handlowe, święta, warunki drogowe, przewoźnicy autobusowi, POI, waluty), wybierz poziom modelu (szybki / zrównoważony / pro — to on ustala cenę), napisz własne instrukcje z symbolami {{feed.slug}} wskazującymi dokładnie, gdzie w odpowiedzi trafiają nasze dane, i dodaj własne zdanie końcowe dołączane do każdej odpowiedzi. Gotowe szablony: osobisty asystent podróży, asystent pracy/transportu, asystent sprzedaży ubezpieczeń i Zielonej Karty.

Przetestuj go w studiu (30 odpowiedzi dziennie, niezależnie od Twojego limitu API), a potem wywołuj produkcyjnie przez GET /api/v2/data/assistant-custom?assistant_id=N&q=…. Cena za odpowiedź = jednostki poziomu modelu + 1 jednostka za każdy włączony kanał, zwracana w X-Devapi-Units. Produkt działa tylko w v2 — adres v1 zwraca unsupported_version. Istniejący produkt assistant pozostaje bez zmian.

Każdy asystent działa pod polityką treści platformy, która ma pierwszeństwo przed Twoimi instrukcjami: żadnego podszywania się pod urzędników, żadnej pomocy w omijaniu kontroli granicznej lub celnej, żadnych zmyślonych liczb, żadnych wulgaryzmów. Sprawdzane są zarówno instrukcje, jak i odpowiedzi; zablokowane wywołania są rejestrowane.

Nowość: prawdziwy serwer MCP pod adresem https://nakordoni.eu/mcp, udostępniający bezpieczny, tylko do odczytu podzbiór API (status, checkpoints, border queue, live queue, forecast) jako narzędzia MCP. Ten sam klucz API i limit co w REST API. Karta serwera pod adresem /.well-known/mcp/server-card.json. Zobacz sekcję Serwer MCP w dokumentacji.

Opisana niżej zmiana nazwy na „Live Queue & Freshness API” w rzeczywistości nie dotarła do strony dokumentacji . Strona wyświetla nazwę każdego produktu przez wyszukiwanie tłumaczenia, które sięga po tytuł punktu końcowego tylko wtedy, gdy tłumaczenia nie ma — a tłumaczenie już istniało, zamrożone na starej nazwie, we wszystkich 25 językach interfejsu. Od teraz ma ono pierwszeństwo przed każdą przyszłą zmianą tytułu bazowego, dopóki samo nie zostanie zaktualizowane.

Klucz tłumaczenia zmieniono we wszystkich 25 językach, więc strona dokumentacji jest już zgodna. Bez zmian w punkcie końcowym, parametrach ani odpowiedzi — wyłącznie tekst tytułu.

Jeśli często odpytujesz dane kolejki na żywo, możesz niepotrzebnie zużywać limit ciężki. /update-info należy do klasy standardowej i już zwraca aktualną wartość:

GET /api/v1/data/update-info?ppid=id_13

Zwraca queue_now, freshness, age_minutes, is_realtime, status, timestamp oraz timezone. Używaj go do częstego odświeżania w ramach standardowego limitu dziennego, a /queue, /multi i /forecast (wszystkie klasy ciężkiej) zostaw na sytuacje, gdy potrzebujesz wait_min, pól trendu lub historii.

W samym punkcie końcowym nic się nie zmieniło — tylko w jego dokumentacji. Był wymieniony jako „Data Freshness API”, a jego opis wspominał wyłącznie o ocenie świeżości, nigdy o queue_now, więc łatwo było go przeoczyć. Teraz nosi nazwę „Live Queue & Freshness API”, z wypisanymi zwracanymi polami. Dziękujemy deweloperowi, który to zgłosił.

Część nieudanych żądań zwracała HTTP 200 z ok: true i błędem ukrytym wewnątrz data — przez co udokumentowany wzorzec if (!ok) throw nie mógł ich wykryć, a wywołanie i tak było naliczane. Takie wywołania zwracają teraz HTTP 400 z ok: false oraz właściwymi error.code / error.message, zgodnie z dokumentacją. Zaobserwowane w fuel-cities przy nieobsługiwanym kraju oraz w travel-matrix przy błędnych współrzędnych.

Osobno: brak wymaganego parametru zwracał 500 internal_error zamiast 400 bad_request (treść odpowiedzi 4xx z usługi wewnętrznej była odrzucana, zanim odczytano jej status). Teraz zwracane jest 400 bad_request z komunikatem z usługi wewnętrznej — np. search bez ?name=.

Udane odpowiedzi są niezmienione co do bajta — te same pola, te same parametry, ten sam koszt limitu. Jeśli Twój klient już rozgałęzia się na ok, nic nie musisz zmieniać. Jeśli ignorował ok i czytał data bezpośrednio, zobaczy teraz koperty błędów przy wywołaniach, które i tak zawsze kończyły się niepowodzeniem.

Naprawiono błąd, przez który /multi mógł zwracać błędną liczbę w kolejce dla części przejść — głównie bałkańskich oraz na granicy Węgry–Serbia — zawsze gdy jego bufor był zimny. Ścieżka zapasowa czytała tabelę, która dla tych przejść nie zawiera danych o kolejce, i podawała niepowiązane wartości jako liczbę samochodów. Zmierzone przykłady: przejście z 12 samochodami raportowało 6, a kilka z realnymi kolejkami raportowało 0.

Trzy zmiany, które możesz zauważyć:

• found: false oznacza teraz, że naprawdę nie ma świeżych danych o kolejce. Wcześniej mogłeś otrzymać found: true ze zmyślonym queue_now: 0.
• wait_status, trend_percent i trend_direction są teraz zwracane przy zimnych żądaniach — wcześniej miały wartość null .
• Punkt końcowy sięga po ścieżkę zapasową także wtedy, gdy jego zapisany stan jest przestarzały (starszy niż 24 h), a nie tylko gdy go brakuje.

Bez zmian w parametrach żądania, koszcie limitu ani strukturze odpowiedzi.

Naprawiono błąd, przez który każde wywołanie /multi było liczone podwójnie — raz przez ogólną kontrolę 1 jednostki, a raz przez własny wzór kosztu zmiennego endpointu (N PPID × podprodukty). Wywołanie kosztuje teraz dokładnie ⌈(N×M)/2⌉ jednostek zgodnie z dokumentacją, bez dodatkowej opłaty.

Na stronie dokumentacji dodano też odznakę klasy limitu (Standard/Heavy) przy każdym produkcie, aby od razu było widać, z jakiego dziennego limitu korzysta dany endpoint.

country i countries scalono w jeden parametr (1-15 kodów oddzielonych przecinkami). Nowy parametr compare_to: porównanie takich samych i różnych świąt między krajami, łączy się z upcoming+days. lang przyjmuje teraz wiele języków (dodaje obiekt names). days=0 lub pominięcie oznacza teraz brak limitu w trybie upcoming.

Oficjalne święta państwowe dla każdego kraju europejskiego — daty, lokalne nazwy i typ. Oparte na tej samej usłudze Nager.Date / OpenHolidaysAPI (z lokalnie obliczanym kalendarzem Kosowa), która zasila stronę kalendarza świąt nakordoni.eu oraz czynniki kalendarzowe systemu prognozowania.

• ?country=PL&year=2026 — pełna roczna lista świąt dla jednego kraju
• ?upcoming=1&days=30 — płaska lista nadchodzących świąt w różnych krajach
• Bez parametrów — indeks podstawowego zestawu krajów z najbliższym świętem dla każdego

Dodano produkt currency — kursy wymiany oparte na EUR dla PLN, CZK, HUF, USD, GBP, CHF, NOK i UAH, pochodzące z Frankfurter (ECB), buforowane przez 6 godzin. Bez parametrów, zawsze zwraca pełną tabelę kursów. Zobacz dokumentację.

Osadź na własnej stronie aktualne europejskie zakazy ruchu ciężarówek — darmowy widget iframe z 3 wzorami (light, dark, board), 5 językami (en, uk, pl, de, ru), opcjonalnym filtrem według kraju i statusem na żywo «aktywny teraz». Klucz API nie jest wymagany. Skonfiguruj i skopiuj kod na nakordoni.eu/en/for_truck_drivers/traffic_bans/widget. Wolisz surowe dane? Produkt API truck-bans oraz publiczny kanał JSON pozostają dostępne.

Trzy nowości, wszystkie wstecznie kompatybilne — v1 bez zmian.

Wersjonowanie na poziomie punktów końcowych. Istnieje teraz bazowy adres URL /api/v2/. Działa ono na poziomie punktów końcowych: inaczej zachowują się tylko te punkty końcowe, które faktycznie się zmieniły; każdy inny punkt końcowy przezroczyście zwraca swoją odpowiedź v1 (więc /api/v2/data/queue = te same dane co v1, tylko z "api_version":"v2"). Nie trzeba migrować działających punktów końcowych.

border v2 jest kierunkowy. Kolejność w ścieżce określa kierunek podróży:

GET /api/v2/data/border/1/2/6   → buses UA→PL (Ukrainian-side crossings)
GET /api/v2/data/border/2/1/6   → buses PL→UA (Polish-side crossings)

Każdy punkt kontrolny otrzymuje też obiekt direction {from,to} oraz wartość logiczną stale, a ?max_age_min=N zwraca tylko niedawno zaktualizowane przejścia. (v1 border nadal zwraca obie strony granicy niezależnie od kolejności — bez zmian.)

Interaktywny Sandbox. Zalogowani deweloperzy mogą teraz wypróbować dowolny punkt końcowy z przeglądarki pod adresem Developers → Sandbox — wybierz punkt końcowy, wersję i jeden ze swoich kluczy, zmień parametry i zobacz odpowiedź na żywo. Testowanie w Sandbox ma własny odrębny dzienny budżet (50 calls/day) i nigdy nie narusza Twojej produkcyjnej kwoty API.

Dokumentacja jest teraz podzielona według punktów końcowych (Developers → API Docs) z przełącznikiem wersji na punktach końcowych, które mają więcej niż jedną wersję.

Dwa nowe czynniki dodane do formuły czasu oczekiwania, obok istniejących korekt section_mode i pogody:

• service_rate — zmierzona liczba aut/min aktualnie obsługiwanych względem skonfigurowanej bazowej przepustowości przejścia. Multiplikatywny, w zakresie 0.5x-1.5x.
• shift_change — wpływ lokalnej zmiany warty straży granicznej o 08:00/20:00 na danym przejściu. Addytywny (minuty), a nie multiplikatywny — stosowany tylko w zakresie +/-60 minut od zmiany, wymaga minimalnej historii próbek, ograniczony do +/-120 minut.

advanced_wait_min to teraz round(base_wait × section_mode × weather × service_rate) + shift_change.adjustment_min. Oba czynniki są też odzwierciedlone w driver_reported.prognosed_advanced_wait_min dla porównań historycznych.

W ramach przeglądu bezpieczeństwa/prywatności usunięto następujące pola — ujawniały wewnętrzne szczegóły implementacji (naszą taksonomię źródeł danych, identyfikatory wierszy BD, wewnętrzne adnotacje potoku, nieużywane/martwe pola) bez realnej wartości produktowej:

• id i corrected — usunięte z obiektów wierszy queue
• source (surowy ciąg, np. "line") — usunięte z queue, multi i update-info. update-info i multi (jego blok update_info) nadal zawierają source_category/source_label_en (niewielki publiczny słownik); queue i multi (jego blok queue) nie zawierają już żadnego pola źródła
• traffic_status — usunięte z border; zawsze było null i nigdy nie było wypełniane przez żadną część systemu

Jeśli Twoja integracja odczytuje którekolwiek z tych pól, zaktualizuj ją — zobacz aktualną listę pól na stronie dokumentacji odpowiedniego produktu.

Dzienne zużycie limitu (usage.used w każdej odpowiedzi) może teraz być wartością dziesiętną (np. 67.5) zamiast zawsze liczbą całkowitą. To efekt uboczny tego, że queue-advanced jest rozliczany według stawki ułamkowej — zobacz poniżej. usage.limit pozostaje bez zmian i zawsze jest liczbą całkowitą. Jeśli Twój klient ściśle typuje usage.used jako liczbę całkowitą, rozszerz go, aby akceptował wartość dziesiętną/zmiennoprzecinkową.

Te trzy produkty zwracają teraz te same pola statusu na żywo, które pokazuje strona: wait_status (green/yellow/red, na podstawie własnej niedawnej historii tego przejścia) oraz trend_percent/trend_direction (up/up-slight/down/down-slight/stable, porównanie ostatnich 3 godzin). Wyłącznie addytywne.

W /api/v1/data/queue wiersze data[] miały wcześniej wait_time: null dla większości źródeł — tylko kilka zewnętrznych kanałów podaje czas oczekiwania bezpośrednio. Wiersze bez niego otrzymują teraz standardowe oszacowanie , oznaczone nową wartością logiczną wait_time_estimated, dzięki czemu odróżnisz wartość rzeczywiście zgłoszoną od wyliczonej.

queue-advanced kosztuje teraz 1.5 jednostki za wywołanie zamiast 1 (odzwierciedlając dodatkowe zapytania o ruch/pogodę/zgłoszenia kierowców, które wykonuje) — zobacz usage.used powyżej. Odpowiedź nie zawiera już także total_crossing_time, a driver_reported to teraz tylko {wait_min, ts, age_min} — poprzednie pola porównania prognozy z rzeczywistością (prognosed_wait_min, diff_min, historical_section_mode, historical_weather itd.) zostały usunięte. section_mode, weather, advanced_wait_min i exceeds_crossing_time pozostają bez zmian.

/api/v1/data/truck-bans zwraca teraz dla każdego kraju w bans_by_country wartość status (active/clear) oraz active_window, next_window, local_time i tz — obliczone we własnej strefie czasowej danego kraju, więc nie musisz już samodzielnie porównywać surowych okien zakazów z zegarem. Odpowiedź dodaje też listę covered_countries najwyższego poziomu oraz znacznik czasu UTC as_of.

GET /api/v1/data/truck-bans?country=PL

Wyłącznie addytywne — istniejące pola current_bans/upcoming_bans/bans_by_country pozostają bez zmian. Nieznany ?country= zwraca teraz pusty wynik z countries_not_covered zamiast zakazów wszystkich krajów.

Nowy opcjonalny produkt, który koryguje standardowy czas oczekiwania o bieżący przepływ ruchu i pogodę. Zwraca pełny rozkład każdej korekty.

GET /api/v1/data/queue-advanced?ppid=id_13

Przyznawany na żądanie — otwórz zgłoszenie Data w swoim panelu, aby go włączyć.

/api/v1/data/border poprawnie oblicza teraz wait_min dla każdego przejścia w odpowiedzi, tak jak produkty queue i multi. Wcześniej to pole zawsze było null.

/api/v1/data/forecast niezawodnie używa teraz modelu zespołowego v4 dla dowolnej wartości prediction_steps (wcześniej niektóre niestandardowe horyzonty mogły po cichu wracać do starszego modelu). Czynnik pogodowy zasilający zespół również poprawiono i teraz naprawdę odzwierciedla bieżące warunki (deszcz, śnieg, wiatr, mgła) zamiast zawsze zgłaszać niedostępność.

Zatwierdzeni deweloperzy mogą teraz pobierać uśrednione godzinowo historyczne dane kolejek granicznych dla maksymalnie 5 przejść (przesuwne okno do 90 dni) w formacie CSV lub NDJSON z nowej zakładki Data export. Dane są wyłącznie opublikowane i sprawdzone pod kątem jakości; znaczniki czasu w UTC. Potrzebujesz dostępu? Otwórz zgłoszenie Data.

Nie masz jeszcze strony? Możesz teraz utworzyć konto dewelopera, opisując, gdzie i jak planujesz wykorzystać nasze dane, zamiast obowiązkowo podawać URL działającej strony. Dodaj prawdziwy URL później ze swojego panelu (Account & data → Your project), gdy tylko Twoja strona lub aplikacja ruszy — widoczny link zwrotny do nakordoni.eu na tej stronie jest wymagany przez nasz Regulamin.

Deweloperzy mogą teraz przesyłać własne wiadomości graniczne do serwisu informacyjnego Nakordoni. Jeśli nasi redaktorzy je opublikują, otrzymasz indeksowalny link dofollow do swojej usługi (wzmianka o wydawcy + wiersz źródła), a my przetłumaczymy artykuł na wszystkie 24 języki za darmo.

Jeden artykuł tygodniowo jest darmowy; dodatkowe artykuły to płatny dodatek. Wybierz 'możemy lekko zredagować + dodać linki wewnętrzne' lub 'opublikuj bez zmian'. Przesyłaj i śledź status weryfikacji w sekcji Developers → Submit news.

Multi-Checkpoint API (/api/v1/data/multi) nalicza teraz limit według wzoru ⌈(N PPIDs × sub-products) / 2⌉ — połowa kosztu równoważnych pojedynczych wywołań. Żądanie dla 10 przejść z obydwoma podproduktami kosztuje teraz 10 jednostek zamiast 20. Nagłówek X-Devapi-Units oraz meta.units_consumed w odpowiedzi odzwierciedlają obniżoną kwotę.

Pobieraj status kolejek na żywo i świeżość danych dla maksymalnie 20 przejść w jednym wywołaniu API — zaprojektowane dla twórców pulpitów, którzy obecnie odpytują wiele PPIDs w pętli.

Limit liczony jest uczciwie jako N PPIDs × sub-products żądanych, więc całkowite zużycie jest identyczne jak przy pojedynczych wywołaniach — ale z jednym zapytaniem zamiast wielu. Wzorce w stylu GreenTravel spadają z 24+ wywołań/godzinę do 2.

GET /api/v1/data/multi?ppids=id_2,id_13,id_15,id_59&include=queue,update-info&lang=en

• include=queue — bieżące queue_now, szacowane wait_min, wiek danych i nazwa przejścia
• include=update-info — świeżość danych, klasyfikacja źródła, wiek w sekundach/minutach
• Maksymalnie 20 PPIDs na żądanie; połącz oba podprodukty w jednym wywołaniu, aby uzyskać pełne dane pulpitu
• Odpowiedź zawiera meta.units_consumed, dzięki czemu możesz precyzyjnie śledzić zużycie limitu

Odpowiedź produktu queue zawiera teraz obiekt snapshot najwyższego poziomu z najnowszymi danymi w czasie rzeczywistym i wyliczonym prognozowanym czasem oczekiwania — ten sam wzór, który jest używany w sekcji hero nakordoni.eu:

snapshot.queue_now  — current cars in queue
snapshot.wait_min   — (minutes)
snapshot.updated_at — when the queue data was recorded
snapshot.age_min    — minutes since last update
snapshot.source     — data source identifier

Tablica data (wpisy historyczne) pozostaje bez zmian — to wyłącznie addytywne rozszerzenie. Klienci, którzy nie odczytują snapshot, nie są tym objęci.

Odpytuj wszystkie przejścia na danej granicy + typ pojazdu jednym wywołaniem zamiast wykonywać osobne żądanie dla każdego PPID.

GET /api/v1/data/border/{origin}/{destination}/{crossing_type}

• Obsługuje pojedynczy kraj docelowy, listę oddzieloną przecinkami lub all, aby rozwinąć na wszystkich monitorowanych sąsiadów naraz.
• Wyniki posortowane według queue_now rosnąco (najkrótsza kolejka najpierw).
• W pełni zlokalizowane: dodaj ?lang=uk (lub dowolny z naszych 22 obsługiwanych języków), aby uzyskać nazwy przejść w tym języku.

Znajduj wartości PPID przejść po nazwie bez przeglądania całego katalogu.

GET /api/v1/data/search?name=Krakovets,Shehyni&lang=en

• Przyjmuje pojedynczą nazwę lub listę oddzieloną przecinkami (do 20).
• Wyszukuje we wszystkich 24 językach tłumaczeń — podaj nazwę po ukraińsku, polsku, niemiecku lub w dowolnym obsługiwanym języku, a zostanie dopasowana.
• Zwraca wszystkie PPIDs w danej lokalizacji pogrupowane według typu pojazdu (samochód / autobus / pieszy / ciężarówka).

Produkt alternatives przyjmuje teraz ?lang= we wszystkich 22 obsługiwanych językach (było tylko 12).

Nowy parametr crossing_type pozwala nadpisać filtr typu pojazdu — np. przekaż crossing_type=4, aby uzyskać alternatywy dla samochodów nawet przy zapytaniu z autobusowego PPID.

Pole crossing_type_label w odpowiedziach checkpoints, border i search jest teraz tłumaczone na żądany język we wszystkich 22 obsługiwanych językach. Pola nazw krajów (origin_name, destination_name) podążają za tą samą lokalizacją.

Portal Nakordoni Developer API działa pod adresem /en/developers. Zarejestruj darmowy klucz Explorer (200 requests/day), aby uzyskać dostęp do danych kolejek granicznych, prognoz, cen paliwa, POI dla kierowców i nie tylko.

Produkty dostępne na starcie: checkpoints, queue, stats, day-stats, forecast, alternatives, update_info, fuel, pois, truck_bans, trading_sundays, bus_carriers, road_conditions, assistant.