API

Jeśli potrzebujesz szybkiej i informacji o kodzie pocztowym, oferujemy do tego prywatne API.

Rozpoznawanie kodu pocztowego

Klient wysyła zapytanie POST na podany, prywatny URL z IP zarejestrowanego wcześniej, na przykład za pomocą mechanizmu CURL.

Przykład w PHP:

  
   $post = "kod=00-950"
           ."&api=k1.0&key={A34531FD-FCD1-4A59-9F02-3622E133F7A0}&email=admin@klienta.pl";
   $ch = curl_init();
   curl_setopt($ch, CURLOPT_USERAGENT, "JZK@IDKLIENTA");
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
   curl_setopt($ch, CURLOPT_CURLOPT_POST, 1);
   curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
   curl_setopt($ch, CURLOPT_HEADER, 1);
   curl_setopt($ch, CURLOPT_NOBODY, 1);
   curl_setopt($ch, CURLOPT_TIMEOUT, 1);
   curl_setopt($ch, CURLOPT_URL, "https://podanyserwer.kodypocztowe.pl");
   curl_setopt($ch, CURLOPT_PROTOCOLS, CURLPROTO_HTTPS);
   $wynik = curl_exec($ch);
   $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); 
   curl_close($ch);
Serwer zwraca prywatny status HTTP, na przykład:
   X-IP: Tw.ó.j.IP OK
   X-Api: {A34531FD-FCD1-4A59-9F02-3622E133F7A0} OK
   X-Kod: 00-950
   X-Teryt: 000000000
   X-Miasto: Warszawa
   X-Pow: m. Warszawa
   X-Woj: mazowieckie
   HTTP/1.0 227 OK 
Klient sprawdza, czy zwrócone dane są identyczne z zapytaniem i jeśli kod odpowiedzi jest zgodny z oczekiwanym, traktuje informację jako prawidłową. Mogą wystąpić inne statusy, na przykład:
   HTTP/1.0 406 Brak uprawnień
albo:
   X-IP: Tw.ó.j.IP OK
   X-Api: {A34531FD-FCD1-4A59-9F02-3622E133F7A0} OK
   X-Kod: blablabla
   X-Info: Nieprawidłowy kod
   HTTP/1.0 456 OK 
albo:
   HTTP/1.0 535 Za dużo wywołań
albo:
   X-IP: Tw.ó.j.IP OK
   X-Api: {A34531FD-FCD1-4A59-9F02-3622E133F7A0} OK
   X-Kod: 00-000
   X-Info: Brak informacji
   HTTP/1.0 457 OK 
Kody odpowiedzi, API etc. są podane dla zobrazowania idei działania. Serwer produkcyjny działa inaczej. Jeśli klient wysyła prawidłowe zapytanie i jest prawidłowo rozpoznany, otrzymuje w odpowiedzi niestandardowe kody odpowiedzi HTTP, zgodne jednak z konwencją: 2xx - OK, 3xx - coś innego, 4xx - odmowa lub brak danych, 5xx - problem z serwerem lub przeciążenie. Jeśli klient nie jest rozpoznany, otrzyma przekierowanie na inną stronę internetową, standardową treść HTML z kodem 200 albo serwer odmówi połączenia z kodem 50X.

Rozpoznawanie adresu

Przykład w PHP:
  
   $post = "ulica=Warszawska&nr=59&miasto=Biała Podlaska&teryt=060103"		
           ."&api=m1.0&key={A34531FD-FCD1-4A59-9F02-3622E133F7A0}&email=admin@klienta.pl";
   $ch = curl_init();
   curl_setopt($ch, CURLOPT_USERAGENT, "JZK@IDKLIENTA");
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
   curl_setopt($ch, CURLOPT_CURLOPT_POST, 1);
   curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
   curl_setopt($ch, CURLOPT_HEADER, 1);
   curl_setopt($ch, CURLOPT_NOBODY, 1);
   curl_setopt($ch, CURLOPT_TIMEOUT, 1);
   curl_setopt($ch, CURLOPT_URL, "https://podanyserwer.kodypocztowe.pl");
   curl_setopt($ch, CURLOPT_PROTOCOLS, CURLPROTO_HTTPS);
   $wynik = curl_exec($ch);
   $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); 
   curl_close($ch);
Im dokładniejszej odpowiedzi oczekujesz, tym bardziej trzeba zadbać o format Twojej bazy danych. Aby prawidłowo rozpoznawać kody pocztowe, trzeba najpierw poddać swoje dane sanityzacji.

Dodatkowe powiązania

Istnieją także zaawansowane możliwości uzyskania odpowiednich powiązań, na przykład kod pocztowy + TERYT + nazwa miejscowości, przykładowo:
   08-504   061606   Ułęż
   21-307   061507   Ulan-Majorat
   22-234   061905   Urszulin
   22-510   060407   Uchanie
   22-678   061813   Ulhówek
   23-250   060708   Urzędów
   34-371   241714   Ujsoły
   37-410   181207   Ulanów
   38-315   120510   Uście Gorlickie
   38-700   180108   Ustrzyki Dolne

Sanityzacja bazy danych

Jeśli baza jest zbudowana prawidłowo, rozpoznaje sytuacje, gdy adresem jest nazwa wsi lub przysiółka, a poczta jest w siedzibie gminy.

Są miejscowości sąsiadujące ze sobą, będące dobrym testem zgodności bazy danych pod kątem formatu zapisu, na przykład:

   060103 Ortel Królewski Pierwszy Piszczac bialski lubelskie 21-530
   060103 Ortel Królewski Drugi Piszczac bialski lubelskie 21-530
   060111 Ortel Książęcy Pierwszy Biała Podlaska bialski lubelskie 21-500
   060111 Ortel Książęcy Drugi Biała Podlaska bialski lubelskie 21-500
Jeśli posiadasz adres o postaci Ortel Królewski 1/5, rozpoznanie nie będzie prawidłowe.
   061404 Kazimierz Dolny (Góry Pierwsze) Kazimierz Dolny puławski lubelskie 24-120
   061404 Kazimierz Dolny (Góry Drugie) Kazimierz Dolny puławski lubelskie 24-120
   061404 Kazimierz Dolny (Góry Trzecie) Kazimierz Dolny puławski lubelskie 24-120
   061407 Góry (Góry-Kolonia) Markuszów puławski lubelskie 24-173 
   061407 Góry Markuszów puławski lubelskie 24-173
   061410 Łyse Góry Wąwolnica puławski lubelskie 24-160
Baza kodów pocztowych zawiera także wesołe wyjątki, na przykład:
   061410 Celejów 1 Wąwolnica puławski lubelskie 24-160 poczta Wąwolnica
   061410 Celejów 29 Wąwolnica puławski lubelskie 24-120 poczta Kazimierz Dolny
Pojawiają się także zmiany podziału administracyjnego
   181612 Bzianka Świlcza rzeszowski podkarpackie 35-213 poczta Świlcza - do 31.12.2016
   186301 Bzianka Rzeszów Rzeszów podkarpackie 35-213 poczta Rzeszów - od 1.01.2017
Z kolei nieco wcześniej przyłączona wieś Słocina posiada już nazwy ulic i kody pocztowe właściwe dla Rzeszowa, na przykład powinno być:
   ul. Św. Rocha 1
   35-330 Rzeszów
podczas gdy w bazie może figurować:
   Słocina, ul. Św. Rocha 1
   36-007 Krasne
albo zgoła:
   ul. Św. Rocha 1
   35-330 Słocina
Należy też zweryfikować, jak zapisywane są adresy zawierające ulicę, nazwę miejscowości oraz nazwę poczty, np.
   Mareza, ul. Główna 11
   82-500 Kwidzyn
Sporym wyzwaniem jest też format zapisu nazw ulic, zwłaszcza o charakterze historycznym, powiązanych z datami etc.

Komfort i bezpieczeństwo

Serwer jest wysoce zoptymalizowany, dzięki czemu możemy sobie i Tobie zapewnić komfort i bezpieczeństwo. Zachowanie odpowiedniej sprawności systemu wymaga współpracy z obu stron. Autoryzacją jest w każdym przypadku para IP+klucz API.

Użytkownik ma prywatny klucz API
Zapytania z niewłaściwym kluczem są ignorowane i powodują blokadę danego IP.

Użytkownik podaje prywatny adres IP
Zapytania z innego IP są ignorowane i powodują blokadę klucza.

Zapytania powinny być kolejkowane
Wysłanie ciągłej serii zapytań przeciąża serwer, traktowane jest jako atak DDoS i powoduje blokadę IP.

Zapytania powinny być buforowane
Dane są statyczne, nie ma potrzeby ani sensu pytać ciągle o to samo.
Serie identycznych zapytań powodują blokadę IP oraz klucza.

Koszty

Wycena dostępu jest zawsze indywidualna. Rekomendujemy wykonanie próbnych zapytań, pozwalające zweryfikować przydatność rozwiązania i posiadaną strukturę bazy danych. Często okazuje się, że posiadane przez klienta bazy wymagają uprzedniej sanityzacji, standaryzacji i deduplikacji.

Wypróbuj wyszukiwanie online


© Studio JZK, 2016. Wszelkie prawa zastrzeżone.
58 782 33 66 (8-19) www.kody-pocztowe.pl

Do profesjonalnych zastosowań wypróbuj nasze Kody Pocztowe TERYT dla Windows oraz dedykowane API on-line.
#33/2048/1495872190

 

Serwis sponsorowany przez Druczka® i Fakturzystę®.