Numer działki ewidencyjnej (ULDK) - wyszukiwarka działek i ich dane, przez API

Numer ewidencyjny ma w środku ukośnik, a ukośnik w ścieżce adresu jest separatorem, nie znakiem. Dlatego /api/v1/parcels/146518_8.0106.110/3 kończy się błędem 400 z podpowiedzią „użyj formy z myślnikiem”, a poprawnie jest 146518_8.0106.110-3. W parametrze q= obie formy przechodzą, ale ukośnik trzeba zakodować jako %2F, bo część klientów HTTP potnie go razem ze ścieżką. Praktyczna reguła: parcel_key z odpowiedzi wstawiasz w adres, parcel_id pokazujesz człowiekowi.

Wybierasz między q=, parcelId= i parą lat= z lng=. Podanie dwóch naraz kończy się błędem 400 „Provide exactly one lookup mode”, i tym samym błędem kończy się puste q=, bo puste znaczy tu „żadnego trybu”. Sam q= ma trzy zachowania: przyjmuje pełny numer, przyjmuje UUID i przyjmuje tekst „nazwa miejscowości plus numer działki”. O tym, które z nich zadziała, decyduje kształt tego, co wpiszesz, więc jedno pole obsługuje i wyszukiwanie po nazwie, i zwykłe sprawdzenie numeru.

Gdy podasz pełny numer, dostajesz go z powrotem, bo już go miałeś. Gdy szukasz po nazwie z numerem albo po punkcie na mapie, parcel_id i parcel_key wracają puste dla wywołań anonimowych i dla darmowych kont w przeglądarce - takie zapytanie odsłaniałoby powiat i obręb, których pytający nie podał. Klucze API, OAuth oraz konta płatne i próbne widzą numer w każdym trybie. Reszty odpowiedzi to nie dotyczy: powierzchnia, nazwa miejscowości, kod powiatu i punkt środkowy wracają zawsze, więc do zlokalizowania działki na mapie sam numer nie jest potrzebny.

Wyszukiwanie może zwrócić dopasowania z kilku powiatów naraz, więc jednej daty dla nich nie ma i as_of podaje najświeższy wczyt w skali kraju. Odpowiedź o pojedynczej działce pod /api/v1/parcels/{numer} podaje datę dla powiatu tej jednej działki, a powiaty odświeżamy w różnym tempie. Dla tej samej działki oba pola potrafią się rozjechać o miesiące i nie jest to błąd: pierwsze mówi o świeżości całej kopii, drugie o świeżości tego jednego powiatu. Świeżość konkretnej działki czytaj z drugiego.

Wyszukiwanie po nazwie z numerem oddaje najwyżej dziesięć dopasowań i ustawia wtedy truncated. Bierze się to stąd, że w jednej gminie ten sam numer powtarza się w wielu obrębach. truncated jest więc sygnałem, żeby zawęzić zapytanie pełnym numerem albo punktem na mapie; ile działek naprawdę nosi ten numer, odpowiedź nie podaje. Uwaga na asymetrię: wyszukiwanie po punkcie też ma limit, pięciu dopasowań, ale truncated przy nim nie wraca - przy działkach nakładających się na siebie szósta odpadnie po cichu. Druga rzecz, ważniejsza od limitu: brak truncated nie znaczy, że masz komplet. Szukamy po ewidencji, którą trzymamy - niemal całej, choć nie w całości i nie na bieżąco - więc krótka lista może brać się też stąd, że części działek jeszcze u nas nie ma. Skalę podaje blok corpus_coverage w odpowiedziach kolekcji.

Wyszukiwanie nie zdejmuje tokenów i nie rusza salda - w nagłówku X-Credits-Cost wraca zero, a zwrotów nie ma, bo nie ma czego zwracać. Klucz z pustym budżetem nadal wyszukuje. Sprawdzany jest za to sam dostęp: klucz z wygasłego okresu próbnego dostaje 402, a wywołania bez klucza mają własny limit liczony na adres i po jego przekroczeniu wracają z 429. Zostaje też limit liczby zapytań na minutę, więc pętla po tysiącach numerów wymaga rozłożenia w czasie.