Specyfikacja API – dataquality.pl

[specyfikacja API dla Python – link]

Zawartość

  • Wprowadzenie
  • Opis komunikacji API
  • Przykładowy nagłówek autoryzacyjny
  • Kody odpowiedzi HTTP
  • Bazowy URL API
  • Lista dostępnych metod API
  • Zadania: Pobieranie listy zadań
  • Zadania: Pobieranie raportu zadania
  • Zadania: Pobieranie statusu zadania
  • Zadania: Pobieranie pliku wynikowego zadania
  • Zadania: Tworzenia nowego zadania
  • Zadania: Usuwanie zadania przetworzonego
  • Zadania: Usuwanie zadania z kolejki
  • Konto: Pobieranie informacji o stanie konta
  • Plik wyjściowy
  • Statusy wyników procesu standaryzacji danych adresowych i geokodowania
  • Lista obiektów JSON
    • Job
    • Config
    • ConfigInputFormat
    • ConfigInputColumn
    • ConfigExtend
    • ConfigModules
    • ConfigDeduplication
    • ConfigClient
    • JobReport
    • JobReportResults
    • JobReportQualityNames
    • AccountStatus
    • JobStatus

 

Wprowadzenie

Celem dokumentu jest opisanie poszczególnych metod interfejsu API dostępnego dla klientów dataquality.pl.

Opis komunikacji API

  • Komunikacja z API realizowana jest w oparciu o protokół HTTP
  • API o architekturze RESTful
  • API odpowiada standardowymi kodami HTTP informując o statusie odpowiedzi.
  • Każde zapytanie do API wymaga przesłania tokena autoryzacyjnego
  • Brak załączonego nagłówka z tokenem lub błędny token będzie skutkował odpowiedzią w postaci kodu błędu 401 Nieautoryzowany dostęp
  • API odpowiada w formacie JSON

Przykładowy nagłówek autoryzacyjny

Nazwa nagłówka Zawartość nagłówka
Authorization Bearer <TOKEN_AUTORYZACYJNY>

 

Kody odpowiedzi HTTP

API w odpowiedzi na zapytanie zwraca kod HTTP informujący o statusie, oraz ewentualną odpowiedź w postaci łańcucha znaków JSON.
Tabela obsługiwanych kodów HTTP:

Kod HTTP Opis
200 Poprawna odpowiedź
201 Utworzono
202 Zapytanie zaakceptowane, lecz jeszcze nie gotowe
204 Zapytanie wykonane, nie wymaga  odpowiedzi
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
403 Dostęp zabroniony, lub wykonanie akcji niedozwolone
404 Nie znaleziono żądanego obiektu
500 Nieoczekiwany błąd podczas przetwarzania zapytania
501 Metoda nie jest zaimplementowana

 

Bazowy URL API

Wszystkie metody API zawarte w tym dokumencie zaczynają się częścią bazową  /api/v1

Lista dostępnych metod API

Metoda API Opis
GET /jobs Pobieranie listy zadań
GET /jobs/{job_id} Pobieranie raportu zadania
GET /jobs/{job_id}/result Pobieranie pliku wynikowego zadania
GET /jobs/{job_id}/status Pobieranie aktualnego statusu zadania
GET /jobs/{job_id}/report Pobieranie raportu zadania
POST /jobs Tworzenia nowego zadania
DELETE /jobs/{job_id} Usuwanie zadania z kolejki
PUT /jobs/{job_id}/stop Zatrzymanie zadania przetwarzania
GET /account/status Pobieranie informacji o stanie konta

 

Zadania: Pobieranie listy zadań

Zwraca listę zadań użytkownika

Metoda
GET /jobs
Wymagane Nagłówki zapytania
Authorization Bearer <TOKEN_AUTORYZACYJNY>
Odpowiedź

List<Job> – w odpowiedzi zwraca tablicę obiektów Job

Możliwe statusy HTTP
200 Poprawna odpowiedź
401 Nieautoryzowany dostęp lub błąd autoryzacji
 Przykłady:

HTTP/1.1 200

Content-Type: application/json

[{“job_id”:”b7432604-492b-42cc-a45b-cf7eec09b7c1″, “name”:”Nowe zadanie”, “status”:”Nowy”, “start_date”:”2016-09-23T16:22:05Z”, “end_date”:”2016-09-23T18:10:52Z”, “source_records”:1,  “processed_records”:100, “price”:100.00}]

 

Zadania: Pobieranie raportu zadania

Zwraca raport zadania

Metoda
GET /jobs/{job_id}
GET /jobs/{job_id}/report
Wymagane Nagłówki zapytania
Authorization Bearer <TOKEN_AUTORYZACYJNY>
Parametry URL
Parametr Obecność Typ Opis
job_id obowiązkowy String Identyfikator zadania
Odpowiedź

JobReport – w odpowiedzi zwraca obiekt JobReport zawierający dane z pliku raportu przeprocesowanego zadania

Możliwe statusy HTTP
200 Poprawna odpowiedź
202 Żądanie zaakceptowane, lecz raport nie jest gotowy
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
404 Nie znaleziono zadania o podanym identyfikatorze
 Przykłady:

HTTP/1.1 200

Content-Type: application/json

{“results”:{“status”:”OK”,”error_description”:””,”input”:1500,”succeed”:1000,”succeed_value”:800,”failed”:500,”level_town”:990,”level_street”:950,”level_building”:800,”level_premises”:500},”quality_issues”:[{“position”:1,”cnt”:350,”total_percent”:70,”reason”:”jakiś powód”},{“position”:2,”cnt”:100,”total_percent”:20,”reason”:”inny powód”},{“position”:3,”cnt”:50,”total_percent”:10,”reason”:”pozostałe powody”}],”quality_names”:{“names_ok”:100,”surnames_ok”:99,”companies_ok”:50,”names_failed”:20,”surnames_failed”:21}}

 

Zadania: Pobieranie statusu zadania

Zwraca status zadania

Metoda
GET /jobs/{job_id}/status
Wymagane Nagłówki zapytania
Authorization Bearer <TOKEN_AUTORYZACYJNY>

Parametry URL

Parametr Obecność Typ Opis
job_id obowiązkowy String Identyfikator zadania
Odpowiedź

JobStatus – w odpowiedzi zwraca obiekt JobStatus zawierający informacje o aktualnym statusie zadania

Możliwe statusy HTTP
200 Poprawna odpowiedź
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
404 Nie znaleziono zadania o podanym identyfikatorze
Możliwe statusy ZADANIA
NEW Nowe zadanie, dopiero utworzone
QUEUED Zadanie oczekujące na wykonanie
EXECUTION Zadanie w trakcie wykonania
FINISHED_NOT_PAID Zadanie zakończone, ale nie opłacone
FINISHED_PAID Zadanie zakończone i opłacone
FINISHED_FAILED Zadanie zakończone niepowodzeniem
 Przykłady:

HTTP/1.1 200

Content-Type: application/json

{“job_id”: “b7432604-492b-42cc-a45b-cf7eec09b7c1″,”status”: “EXECUTION”}

 

Zadania: Pobieranie pliku wynikowego zadania

Zwraca plik wynikowy zadania CSV

Metoda
GET /jobs/{job_id}/result
Wymagane Nagłówki zapytania
Authorization Bearer <TOKEN_AUTORYZACYJNY>
Parametry URL
Parametr Obecność Typ Opis
job_id obowiązkowy String Identyfikator zadania
Odpowiedź

W odpowiedzi otrzymujemy plik wynikowy CSV

Możliwe statusy HTTP
200 Poprawna odpowiedź
202 Żądanie zaakceptowane, lecz raport nie jest gotowy
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
404 Nie znaleziono zadania o podanym identyfikatorze
 Przykłady:

HTTP/1.1 200

Content-Type: text/csv

Content-Disposition: attachment; filename=”b7432604-492b-42cc-a45b-cf7eec09b7c1_result.csv”

 

HTTP/1.1 404

Content-Type: application/json

{“code”: 404, “message”: “Zadanie nie zostało znalezione”}

 

HTTP/1.1 400

Content-Type: application/json

{“code”: 400, “errors”: [{“field”: “job_id”, “message”:”Niepoprawny identyfikator zadania”}], “message”: “Niepoprawne zapytanie”}

 

Zadania: Tworzenia nowego zadania

Tworzy nowe zadanie na podstawie wgrywanego pliku i załączonej konfiguracji. Specyfikacja obiektu Config zawiera dodatkowe informacje o konfiguracji i definicji pliku wejściowego.

Metoda
POST /jobs
Wymagane Nagłówki zapytania
Authorization Bearer <TOKEN_AUTORYZACYJNY>
Content-Type multipart/form-data; boundary={znacznik_graniczny}
Content-Length {rozmiar_zawartości_requestu}
Parametry POST
Parametr Obecność Typ Opis
file obowiązkowy File Plik CSV do przetworzenia
config obowiązkowy String Obiekt JSON Config
Odpowiedź

W odpowiedzi otrzymujemy utworzony obiekt Job

Możliwe statusy HTTP
201 Utworzono
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
Przykłady:

HTTP/1.1 201 Created

Location: http://adresurlapi.pl/jobs/f390eaf6-bade-46e2-bcfd-4695a59445e8

Content-Type: application/json

{“job_id”:”b7432604-492b-42cc-a45b-cf7eec09b7c1″, “name”:”Nowe zadanie”, “status”:”Nowy”, “start_date”:”2016-09-23T16:22:05Z”, “end_date”:”2016-09-23T18:10:52Z”, “source_records”:1,  “processed_records”:100, “price”:100.00}

 

HTTP/1.1 400

Content-Type: application/json

{“code”: 400, “message”: “Niepoprawny identyfikator zadania”}

 

Zadania: Usuwanie zadania przetworzonego

Usuwa zadanie w statusach:

  • FINISHED_NOT_PAID
  • FINISHED_PAID
  • FINISHED_FAILED

UWAGA: Usunięcie zadania w statusie EXECUTION nie jest możliwe.

Metoda
DELETE /jobs/{job_id}
Wymagane Nagłówki zapytania
Authorization Bearer <TOKEN_AUTORYZACYJNY>
Parametry URL
Parametr Obecność Typ Opis
job_id obowiązkowy String Identyfikator zadania
Odpowiedź

W odpowiedzi otrzymujemy status 204 potwierdzający poprawne usunięcie zadania

Możliwe statusy HTTP
204 Zapytanie wykonane
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
Przykłady:
HTTP/1.1 204 No Content

 

HTTP/1.1 400

Content-Type: application/json

{“code”: 400, “message”: “Niepoprawny identyfikator zadania”}

 

HTTP/1.1 404

Content-Type: application/json

{“code”: 404, “message”: “Zadanie nie zostało znalezione”}

 

Zadania: Usuwanie zadania z kolejki

Usuwa zadanie w statusach:

  • NEW
  • QUEUED

UWAGA: Usunięcie zadania w statusie EXECUTION nie jest możliwe.

Metoda
PUT /jobs/{job_id}/stop
Wymagane Nagłówki zapytania
Authorization Bearer <TOKEN_AUTORYZACYJNY>
URL Params
Parametr Obecność Typ Opis
job_id obowiązkowy String Identyfikator zadania
Odpowiedź

W odpowiedzi otrzymujemy status 204 potwierdzający poprawne zatrzymanie zadania

Możliwe statusy HTTP
204 Zapytanie wykonane
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
Przykłady:
HTTP/1.1 204 No Content

 

HTTP/1.1 400

Content-Type: application/json

{“code”: 400, “message”: “Niepoprawny identyfikator zadania”}

 

HTTP/1.1 404

Content-Type: application/json

{“code”: 404, “message”: “Zadanie nie zostało znalezione”}

 

Konto: Pobieranie informacji o stanie konta

Zwraca informacje o koncie użytkownika

Metoda
GET /account/status
Wymagane Nagłówki zapytania
Authorization Bearer <TOKEN_AUTORYZACYJNY>
Odpowiedź

W odpowiedzi otrzymujemy status obiekt AccountStatus

Możliwe statusy HTTP
200 Poprawna odpowiedź
400 Nieprawidłowe zapytanie lub błąd podczas przetwarzania zapytania
401 Nieautoryzowany dostęp lub błąd autoryzacji
Przykłady:

HTTP/1.1 200 OK

Content-Type: application/json

{“email”: “test2@3e.pl”, “balance”: 1000, “total_records”: 100}

 

HTTP/1.1 400

Content-Type: application/json

{“code”: 400, “message”: “Błąd podczas przetwarzania zapytania”}

 

Plik WYJśCIOWY

Plik wyjściowy zawiera następujące informacje:

  • Wszystkie kolumny wejściowe, poza kolumnami z funkcją POMIN
  • out_id – Kolumnę z id odpowiadającym wartością w kolumnie wejściowej z funkcją ID_REKORDU
  • Dla włączonego modułu address dołączane są informacje
    • out_miejscowosc – Nazwa miejscowości podstawowej
    • out_czesc_miejsc – Nazwa części miejscowości wyodrębnianej przez GUS. Jeśli nie wyodrębniono części miejscowości lub wyodrębniono część miejscowości, która jest tożsama z miejscowością podstawową to pole będzie puste.
    • out_ulica – Nazwa ulicy tworzona przez Algolytics na podstawie pól nazwy ulicy GUS m.in. przez eliminację powtórzeń oraz cechy ul.
    • out_ulica_cecha – Cecha nazwa ulicy GUS: ul., al., pl. itp.
    • out_ulica_nazwa_1 – Główna część nazwy ulicy GUS (np. nazwisko patrona).
    • out_ulica_nazwa_2 – Pierwsza, mniej istotna część nazwy ulicy, o ile istnieje (np. imię patrona).
    • out_kod – Kod pocztowy w formacie: NN-NNN, gdzie N to cyfra <0; 9>.
    • out_nr_domu – Numer domu/budynku.
    • out_nr_miesz – Numer mieszkania.
    • out_gmina – Nazwa gminy.
    • out_powiat – Nazwa powiatu.
    • out_wojewodztwo – Nazwa wojewodztwa.
    • out_mieszkania – Liczba mieszkań w budynku według GUS.
    • out_osoby_prawne – Liczba osób prawnych oraz jednostek organizacyjnych wpisanych do rejestru REGON, które mają siedzibę w danym budynku.
    • out_adr_id – Unikalny identyfikator adresu, niezmienny w czasie.
    • Kolumny dołączane po włączeniu opcji teryt w konfiguracji wejściowej – Obiekt JSON ConfigExtend
      • out_sym_msc – Symbol miejscowości podstawowej GUS TERYT.
      • out_sym_cz_msc – Symbol części miejscowości GUS TERYT. Jeśli nie wyodrębniono części miejscowości lub wyodrębniono część miejscowości, która jest tożsama z miejscowością podstawową to pole będzie puste.
      • out_sym_ul – Symbol nazwy ulicy GUS TERYT
      • out_gmina06 – Sześcioznakowy kod gminy, składany z kodów: województwa (pozycje1-2), powiatu w województwie (pozycje 3-4), gminy w powiecie (pozycje 5-6)
      • out_rodz_gmi – Cyfrowe oznaczenie rodzaju gminy: 1 – gmina miejska, 2 – gmina wiejska, 4 – część miejska gminy miejsko-wiejskiej, 5 – część wiejska gminy miejsko-wiejskiej
      • out_rodzaj_gminy – Słowne oznaczenie rodzaju gminy – patrz out_rodz_gmi
    • Kolumny dołączane po włączeniu opcji gus w konfiguracji wejściowej – Obiekt JSON ConfigExtend
      • out_rejon13 – Kod gminy, wraz z określeniem jej typu (pozycje 1-7) oraz rejonu statystycznego (pozycje 8-13) GUS TERYT
      • out_obwod14 – Kod gminy, wraz z określeniem jej typu (pozycje 1-7), rejonu statystycznego (pozycje 8-13) oraz obwodu spisowego w obrębie tego rejonu (pozycja 14) GUS TERYT;
    • Kolumny dołączane po włączeniu opcji geocode w konfiguracji wejściowej – Obiekt JSON ConfigExtend
      • out_wsp_x – Długość geograficzna wschodnia.
      • out_wsp_y – Szerokość geograficzna północna.
    • Kolumny dołączane po włączeniu opcji diagnostic w konfiguracji wejściowej – Obiekt JSON ConfigExtend
      • out_status – Sekwencja połączonych wpisów w postaci <kategoria: wynik> lub <kategoria>. Szerszy opis pola znajduje się w rozdziale Statusy wyników procesu standaryzacji danych adresowych i geokodowania.
    • Kolumny dołączane po włączeniu opcji building_info w konfiguracji wejściowej – Obiekt JSON ConfigExtend
      • out_zamieszkane – Liczba mieszkań zamieszkanych w budynku według GUS.
      • out_mieszkancy – Liczba mieszkańców w budynku według GUS.
      • out_popul_miesz – Liczba mieszkań zamieszkanych w budynku według rejestru PESEL.
      • out_popul_os – Liczba mieszkańców w budynku według rejestru PESEL.
      • out_popul_kob – Liczba kobiet zamieszkałych w budynku według rejestru PESEL.
      • out_popul_mez – Liczba mężczyzn zamieszkałych w budynku według rejestru PESEL.
      • out_popul_0_4k – Liczba kobiet w wieku do 4 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_5_9k – Liczba kobiet w wieku od 5 do 9 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_10_14k – Liczba kobiet w wieku od 10 do 14 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_15_19k – Liczba kobiet w wieku od 15 do 19 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_20_24k – Liczba kobiet w wieku od 20 do 24 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_25_29k – Liczba kobiet w wieku od 25 do 29 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_30_34k – Liczba kobiet w wieku od 30 do 34 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_35_39k – Liczba kobiet w wieku od 35 do 39 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_40_44k – Liczba kobiet w wieku od 40 do 44 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_45_49k – Liczba kobiet w wieku od 45 do 49 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_50_54k – Liczba kobiet w wieku od 50 do 54 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_55_59k – Liczba kobiet w wieku od 55 do 59 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_60_64k – Liczba kobiet w wieku od 60 do 64 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_65k – Liczba kobiet w wieku powyżej 65 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_0_4m – Liczba mężczyzn w wieku do 4 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_5_9m – Liczba mężczyzn w wieku od 5 do 9 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_10_14m – Liczba mężczyzn w wieku od 10 do 14 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_15_19m – Liczba mężczyzn w wieku od 15 do 19 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_20_24m – Liczba mężczyzn w wieku od 20 do 24 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_25_29m – Liczba mężczyzn w wieku od 25 do 29 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_30_34m – Liczba mężczyzn w wieku od 30 do 34 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_35_39m – Liczba mężczyzn w wieku od 35 do 39 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_40_44m – Liczba mężczyzn w wieku od 40 do 44 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_45_49m – Liczba mężczyzn w wieku od 45 do 49 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_50_54m – Liczba mężczyzn w wieku od 50 do 54 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_55_59m – Liczba mężczyzn w wieku od 55 do 59 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_60_64m – Liczba mężczyzn w wieku od 60 do 64 lat zamieszkałych w budynku według rejestru PESEL.
      • out_popul_65m – Liczba mężczyzn w wieku powyżej 65 lat zamieszkałych w budynku według rejestru PESEL.
      • out_urzad_s – Nazwa urzędu skarbowego właściwego dla adresu.
  • Dla włączonego modułu names dołączane są informacje
    • out_osoba_1_imiona – Wyodrębnione pierwsze imię.
    • out_osoba_1_nazwisko – Wyodrębnione pierwsze nazwisko.
    • out_osoba_1_plec – Określenie płci na podstawie pól out_osoba_1_imiona i out_osoba_1_nazwisko. Możliwe wartości: k – kobieta, m – mężczyzna.
    • out_osoba_2_imiona – Wyodrębnione drugie imię.
    • out_osoba_2_nazwisko – Wyodrębnione drugie nazwisko.
    • out_osoba_2_plec – Określenie płci na podstawie pól out_osoba_2_imiona i out_osoba_2_nazwisko. Możliwe wartości: k – kobieta, m – mężczyzna.
    • out_osoba_3_imiona – Wyodrębnione trzecie imię.
    • out_osoba_3_nazwisko – Wyodrębnione trzecie nazwisko.
    • out_osoba_3_plec – Określenie płci na podstawie pól out_osoba_3_imiona i out_osoba_3_nazwisko. Możliwe wartości: k – kobieta, m – mężczyzna.
    • out_nazwa_przeds – Nazwa przedsiębiorstwa.
    • out_forma_przeds – Forma prawna przedsiębiorstwa.
  • Dla włączonego modułu contact dołączane są informacje
    • out_email1_std – Rozpoznany prawidłowy adres email.
    • out_email2_std – Rozpoznany prawidłowy adres email.
    • out_telefon1_std – Rozpoznany prawidłowy numer telefonu, zaczynający się od znaku “+” i prefiksu międzynarodowego.
    • out_telefon2_std – Rozpoznany prawidłowy numer telefonu, zaczynający się od znaku “+” i prefiksu międzynarodowego.
  • Dla włączonego modułu id_numbers dołączane są informacje
    • out_pesel_std – Rozpoznany prawidłowy numer PESEL.
    • out_pesel_data_ur – Data urodzenia zakodowana w numerze PESEL.
    • out_pesel_plec – Płeć zakodowana w numerze PESEL.
    • out_nip_std – Rozpoznany prawidłowy numer NIP.
    • out_regon_std – Rozpoznany prawidłowy numer REGON.

UWAGA: W przypadku braku możliwości wyciągnięcia którejś z informacji na podstawie danych wejściowych kolumna zawierająca daną informacje będzie pusta.

Statusy wyników procesu standaryzacji danych adresowych i geokodowania

W polu out_status tabeli wynikowej znajduje się sekwencja połączonych wpisów w postaci <kategoria: wynik> lub <kategoria>. Możliwe są następujące kategorie:

  • przypisanie niejednoznaczne – Wpisy pasują w bardzo podobnym stopniu do różnych kandydatów – możliwe wyniki:
    • wybrano jedną z podobnie dopasowanych ulic w jednej miejscowości – Przypisywane są dane jednej z ulic.
    • wybrano jedną z podobnie dopasowanych miejscowości w jednej gminie – Przypisywane są dane jednej z miejscowości.
    • podobnie dopasowane miejscowości w różnych gminach – Nie osiągnięto minimalnej dokładności przypisania, żadne dane nie są przypisywane do danego rekordu.
  • adres w sąsiedniej miejscowości – Adres przypisany do ulicy w jednej miejscowości w rzeczywistości znajduje się już w drugiej, sąsiedniej, przy tej samej ulicy.
  • zmiana nazwy miejscowości – Nazwa miejscowości zmieniła się od czasu wprowadzenia do przetwarzanego zbioru, na wyjściu podano nową nazwę miejscowości.
  • zmiana nazwy ulicy – Nazwa ulicy zmieniła się od czasu wprowadzenia do przetwarzanego zbioru, na wyjściu podano nową nazwę ulicy.
  • dopasowanie – Poziom dopasowania adresu. Możliwe wyniki:
    • mieszkanie – Zidentyfikowano mieszkanie o danym adresie.
    • budynek, w którym nie ma mieszkań – Zidentyfikowano budynek o danym adresie, i budynek ten nie ma mieszkań, a zatem osiągnięto maksymalne możliwe dopasowanie.
    • budynek, w którym są mieszkania – Zidentyfikowano budynek o danym adresie, budynek ten ma jednak mieszkania, tymczasem numer mieszkania nie został rozpoznany.
    • budynek o tym samym numerze całkowitym – Nie zidentyfikowano budynku o danym adresie, ale w danej miejscowości i na danej ulicy jest budynek o tym samym numerze całkowitym – np. W przetwarzanym zbiorze wystąpił numer 18b, którego nie ma w słowniku, jest w nim natomiast budynek o numerze 18.
    • sąsiedni budynek – Nie zidentyfikowano budynku o danym adresie, ale w danej miejscowości i na danej ulicy jest budynek o numerze całkowitym różniącym się o nie więcej niż 4 od numeru całkowitego budynku zawartego w przetwarzanych danych.
    • ulica – Zidentyfikowano ulicę, nie odnaleziono budynku o danym numerze ani numerze sąsiednim.
    • miejscowość, która nie ma ulic – Zidentyfikowano miejscowość, miejscowość nie ma ulic, nie odnaleziono budynku o danym numerze ani numerze sąsiednim.
    • miejscowość – Zidentyfikowano miejscowość, nie odnaleziono ulicy ani przypisanego bezpośrednio do miejscowości budynku o danym numerze ani numerze sąsiednim (w niektórych wsiach występują adresy mieszane – część adresów jest przypisana do poziomu miejscowości, a inne do ulicy).
    • brak – Nie uzyskano dopasowania, nie zidentyfikowano miejscowości.
    • mieszkanie na prawdopodobnej ulicy – Adres został dopasowany do poziomu mieszkania. Adres mógł być dopasowany do różnych ulic, a wybrana została ulica o największym stopniu zgodności z wprowadzoną nazwą ulicy.
    • mieszkanie w prawdopodobnej miejscowości – Adres został dopasowany do poziomu mieszkania. Adres mógł być dopasowany do różnych miejscowości, a wybrana została miejscowość o największym stopniu zgodności z wprowadzoną nazwą miejscowości.
    • budynek, w którym nie ma mieszkań, na prawdopodobnej ulicy – Analogicznie jak w przypadku mieszkanie na prawdopodobnej ulicy, ale adres został dopasowany do poziomu budynek, w którym nie ma mieszkań.
    • budynek, w którym nie ma mieszkań, w prawdopodobnej miejscowości – Analogicznie jak w przypadku mieszkanie w prawdopodobnej miejscowości, ale adres został dopasowany do poziomu budynek, w którym nie ma mieszkań.
    • budynek, w którym są mieszkania, na prawdopodobnej ulicy – Analogicznie jak w przypadku mieszkanie na prawdopodobnej ulicy, ale adres został dopasowany do poziomu budynek, w którym są mieszkania.
    • budynek, w którym są mieszkania, w prawdopodobnej miejscowości – Analogicznie jak w przypadku mieszkanie w prawdopodobnej miejscowości, ale adres został dopasowany do poziomu budynek, w którym są mieszkania.
    • prawdopodobna ulica – Analogicznie jak w przypadku mieszkanie na prawdopodobnej ulicy, ale adres został dopasowany do poziomu ulica.
    • prawdopodobna miejscowość, która nie ma ulic – Analogicznie jak w przypadku mieszkanie w prawdopodobnej miejscowości, ale adres został dopasowany do poziomu miejscowość, która nie ma ulic.
    • prawdopodobna miejscowość – Analogicznie jak w przypadku mieszkanie w prawdopodobnej miejscowości, ale adres został dopasowany do poziomu miejscowość.
  • geokodowanie – Możliwe wyniki:
    • dopasowany budynek – Przypisano współrzędne budynku określonego przez wyniki kategorii dopasowanie:
      • mieszkanie
      • budynek, w którym nie ma mieszkań
      • budynek, w którym są mieszkania
      • budynek o tym samym numerze całkowitym
      • mieszkanie na prawdopodobnej ulicy
      • mieszkanie w prawdopodobnej miejscowości
      • budynek, w którym nie ma mieszkań, na prawdopodobnej ulicy
      • budynek, w którym nie ma mieszkań, w prawdopodobnej miejscowości
      • budynek, w którym są mieszkania, na prawdopodobnej ulicy
      • budynek, w którym są mieszkania, w prawdopodobnej miejscowości
    • sąsiedni budynek – Przypisano współrzędne budynku w danej miejscowości i na danej ulicy (o ile ulica występuje w adresie), o innym numerze, którego całkowita część numeru różni się od całkowitej części numeru danego budynku o nie więcej niż 4.
    • środek ulicy w obrębie kodu pocztowego (<kategoria liczby budynków w grupie>) – W przypadku ulicy, dla której występuje więcej niż jeden kod pocztowy, i kod pocztowy jest znany, przypisano współrzędne środka grupy budynków znajdujących się na określonej ulicy i mających dany kod. W nawiasie podana jest kategoria liczby budynków stanowiących tak określoną grupę:
      • Mniej niż 20 budynków.
      • 20-49 budynków.
      • 50 i więcej budynków.
    • środek ulicy w części miejscowości (<kategoria liczby budynków w grupie>) – W przypadku miejscowości, które mają wyodrębnione części, a dana ulica znajduje się w więcej niż jednej z nich i udało się określić, o którą część chodzi, przypisano współrzędne środka grupy budynków znajdujących się na danej ulicy i w określonej części miejscowości (np. środek ulicy Puławska w części miejscowości Mokotów). W nawiasie podana jest kategoria liczby budynków stanowiących tak określoną grupę:
      • Mniej niż 20 budynków.
      • 20-49 budynków.
      • 50 i więcej budynków.
    • środek ulicy (<kategoria liczby budynków w grupie>) – Przypisano współrzędne środka grupy budynków znajdujących się na danej ulicy; w nawiasie podana jest kategoria liczby budynków stanowiących tak określoną grupę:
      • Mniej niż 20 budynków.
      • 20-49 budynków.
      • 50 i więcej budynków.
    • środek obwodu – Przypisano współrzędne środka obwodu spisowego GUS – terytorium Polski jest podzielone na ponad 180 tysięcy takich obwodów  w oparciu o rozmieszczenie ludności, typowy obwód zamieszkuje około 200 osób.
    • środek rejonu – przypisano współrzędne środka rejonu statystycznego GUS – terytorium Polski jest podzielone na ponad 30 tysięcy takich rejonów w oparciu o rozmieszczenie ludności, typowy rejon zamieszkuje około 1200 osób / 400 gospodarstw domowych.
    • środek miejscowości – Przypisano współrzędne środka miejscowości.
    • brak – nie przypisano współrzędnych.

Lista obiektów JSON

Job

Zmienna Typ Opis
job_id String Unikalny identyfikator zadania nadawany przez aplikację DQ Batch.
name String Nazwa zadania definiowana przez użytkownika.
status String Status mówiący o tym na jakim etapie procesowania znajduje się zadanie. Możliwe statusy zostały wymienione w opisie metody POBIERANIE STATUSU ZADANIA.
start_date String Data i czas rozpoczęcia przetwarzania zadania w formacie ISO 8601: YYYY-MM-DDThh:mm:ssTZD (np. 2018-11-14T19:59:21Z dla UTC, 2018-11-14T20:59:21+01:00 dla UTC+1). Czas liczony od momentu przejścia zadania w stan EXECUTION.
end_date String Data i czas zakończenia przetwarzania zadania (przed naliczeniem opłat za zadanie) w formacie ISO 8601: YYYY-MM-DDThh:mm:ssTZD.
source_records Number Liczba rekordów w pliku wejściowym.
processed_records Number Liczba rekordów poprawnie przeprocesowanych.
price Number Koszt w PLN.

{

“job_id”: “b7432604-492b-42cc-a45b-cf7eec09b7c1”,
“name”: “Nowe zadanie”,
“status”: “Nowy”,
“start_date”: “2016-09-23T16:22:05Z”,
“end_date”: “2016-09-23T18:10:52Z”,
“source_records”: 1000,
“processed_records”: 900,
“price”: 450.00

}

 

Config

Zmienna Typ Opis
job_name String Nazwa zadania definiowana przez użytkownika.
input_format ConfigInputFormat Obiekt zagnieżdżony ConfigInputFormat.
input_columns Array Tablica obiektów typu ConfigInputColumn.
extend ConfigExtend Obiekt zagnieżdżony ConfigExtend.
module_std ConfigModules Obiekt zagnieżdżony ConfigModules.
deduplication ConfigDeduplication Obiekt zagnieżdżony ConfigDeduplication.
client ConfigClient Obiekt zagnieżdżony ConfigClient.

{

“job_name”: “Nazwa zadania”,
“input_format”: ConfigInputFormat,
“input_columns”: [ConfigInputColumn,ConfigInputColumn],
“extend”: ConfigExtend,
“module_std”: ConfigModules,
“deduplication”: ConfigDeduplication,
“client”:ConfigClient

}

 

ConfigInputFormat

Zmienna Typ Opis
format String Wspierane są formaty csv i xlsx.
field_separator String Separator kolumn w pliku wejściowym – wykorzystywane w przypadku pliku csv. W przypadku pliku xlsx powinna być użyta wartość “,”.
text_delimiter String Znaczniki pomiędzy którymi znajduje się wartość tekstowa. Domyślnie pusty znacznik oznacza że tekst jest przekazywany bez takich znaczników. W przypadku pliku xlsx powinna być użyta wartość pusta.
code_page String Kodowanie pliku.
header Boolean Wartość musi być pozostawiona na 1.

{

“format”: “csv”,
“field_separator”: “,”,
“text_delimiter”: “”,
“code_page”: “utf-8”,
“header”: 1

}

 

ConfigInputColumn

Zmienna Typ Opis
no Number Numer kolumny w pliku wejściowym. Numerowanie rozpoczynamy od 0.
name String Nazwa kolumny w pliku wejściowym.
function String Funkcja kolumny. Opis dostępnych funkcji znajduje się poniżej.

Definicja kolumny w pliku wejściowym. Kolumny numerujemy zaczynając od 0.

{

“no”: 0,
“name”: “name”,
“function”: “KOD_POCZTOWY”

}

Zmienna function określa jaki typ danych znajduje się w danej kolumnie pliku wejściowego. Każda kolumna w pliku wejściowym może mieć tylko jedną funkcję. Każda funkcja w pliku wejściowym może wystąpić tylko raz. Wyjątek stanowią funkcje PRZEPISZ i POMIN, które mogą występować wielokrotnie. Dopuszczalne jest wysłanie kilku kolumn o funkcjach zawierających tę samą informację np. numer mieszkania, przy czym użytkownik powinien zadbać o to, aby taka informacja nie była powielona w wielu kolumnach. Funkcjonalność służy do tego aby możliwe było prze-procesowanie wierszy o tych samych informacjach rozłożonych w kolumnach o różnych funkcjach. W przypadku gdy dany wiersz nie wykorzystuje danej funkcji, wartość funkcji w danym wierszu powinna być pusta. Możliwe są następujące wartości zmiennej function:

  • Zmienna adresowa
    • KOD_POCZTOWY
    • MIEJSCOWOSC
    • ULICA_NUMER_DOMU_I_MIESZKANIA
    • ULICA
    • NUMER_DOMU
    • NUMER_MIESZKANIA
    • NUMER_DOMU_I_MIESZKANIA
    • WOJEWODZTWO
    • POWIAT
    • GMINA
  • Zmienna nazw
    • IMIE
    • NAZWISKO
    • NAZWA_PODMIOTU
    • IMIE_I_NAZWISKO
  • Zmienna osób/firm
    • PESEL
    • NIP
    • REGON
  • Zmienna kontaktowa
    • EMAIL1
    • EMAIL2
    • TELEFON1
    • TELEFON2
  • Zmienna datowa
    • DATA_URODZENIA
    • CZAS_AKTUALIZACJI
  • Zmienna niesprecyzowana
    • DANE_OGOLNE – zmienna zostanie przeanalizowana pod kątem wszystkich możliwych informacji
  • Identyfikator
    • ID_REKORDU
  • Zmienna neutralna
    • PRZEPISZ – kopiuje zmienną do pliku wyjściowego
    • POMIN – nie kopiuje zmiennej do pliku wyjściowego

W przypadku wybrania różnych funkcji, ale zawierających tę samą informację (np. ULICA_NUMER_DOMU_I_MIESZKANIA, NUMER_DOMU_I_MIESZKANIA), w zależności od kombinacji, wyróżnić można następujące reguły dla modułu adresowego:

  • jeśli istnieje kolumna ULICA, to wszystkie informacje w ULICA_NUMER_DOMU_I_MIESZKANIA są ignorowane
  • jeśli istnieje kolumna NUMER_DOMU, to wszystkie informacje na temat numeru domu i mieszkania z ULICA_NUMER_DOMU_I_MIESZKANIA oraz NUMER_DOMU_I_MIESZKANIA są ignorowane
  • jeśli nie istnieje kolumna NUMER_DOMU, to kolumna NUMER_MIESZKANIA jest ignorowana
  • jeśli nie istnieje kolumna ULICA i istnieje kolumna ULICA_NUMER_DOMU_I_MIESZKANIA, to kolumna NUMER_DOMU_I_MIESZKANIA jest ignorowana
  • jeśli istnieje którakolwiek z kolumn (KOD_POCZTOWY, MIEJSCOWOSC, ULICA_NUMER_DOMU_I_MIESZKANIA, ULICA, NUMER_DOMU, NUMER_DOMU_I_MIESZKANIA), to kolumna DANE_OGOLNE jest ignorowana

Powyższe reguły mają zastosowanie jedynie do modułu adresowego – wszystkie moduły (address, names, contact, id_numbers) są od siebie niezależne. Analogicznie, dla modułu czyszczącego nazwy, obowiązują następujące reguły:

  • jeśli istnieje kolumna IMIE lub NAZWISKO, to kolumna IMIE_I_NAZWISKO jest ignorowana
  • jeśli istnieje którakolwiek z kolumn (IMIE, NAZWISKO, IMIE_I_NAZWISKO), to kolumna DANE_OGOLNE jest ignorowana

 

ConfigExtend

Zmienna Typ Opis
teryt Boolean Uruchamia moduł dołączający symbole TERYT GUS miejscowości, ulicy, gminy.
gus Boolean Uruchamia moduł dołączający kody rejonów statystycznych i obwodów spisowych GUS.
geocode Boolean Uruchamia moduł dołączający współrzędne geograficzne adresu.
building_info Boolean Uruchamia moduł dołączający liczbę mieszkań i mieszkańców budynku.
diagnostic Boolean Uruchamia moduł dołączający status dopasowania i geokodowania.
area_characteristic Boolean Opcja nie wykorzystywana w obecnej wersji aplikacji.

Opis wartości zwracanych w zależności od konfiguracji obiektu ConfigExtend został umieszczony w rozdziale Plik wyjściowy. UWAGA: opcja area_characteristic nie jest obecnie wykorzystywana.

{

“teryt”: 0,
“gus”: 0,
“geocode”: 0,
“building_info”: 0,
“diagnostic”: 0,
“area_characteristic”: 0

}

 

ConfigModules
Definiuje jakie moduły mają być włączone przy procesowaniu pliku wejściowego.

Zmienna Typ Opis
address Boolean Określa wykorzystanie modułu do czyszczenia danych adresowych. Pełen zakres informacji zwracanych jest opisany w rozdziale Plik wyjściowy.
names Boolean Określa wykorzystanie modułu do czyszczenia nazw – imion, nazwisk, informacje o płci oraz nazwy przedsiębiorstw. Pełen zakres informacji zwracanych jest opisany w rozdziale Plik wyjściowy.
contact Boolean Określa wykorzystanie modułu do czyszczenia danych kontaktowych. Pełen zakres informacji zwracanych jest opisany w rozdziale Plik wyjściowy.
id_numbers Boolean Określa wykorzystanie modułu do czyszczenia numerów identyfikacyjnych. Pełen zakres informacji zwracanych jest opisany w rozdziale Plik wyjściowy.

{

“address”: 1,
“names”: 0,
“contact”: 0,
“id_numbers”: 0

}

Każdy z modułów do poprawnego działania wymaga kolumn z odpowiednią funkcją:

  • “address” – wymaga kolumny z funkcją “DANE_OGOLNE” lub kolumn z funkcjami “KOD_POCZTOWY” i “MIEJSCOWOSC”
  • “names” – wymaga kolumny z funkcją “DANE_OGOLNE” lub co najmniej jednej kolumn z funkcją nazw (dostępne zmienne nazw zostały przedstawione w opisie ConfigInputColumn)
  • “contact” – wymaga kolumny z funkcją “DANE_OGOLNE” lub co najmniej jednej kolumn z funkcją kontaktową (zmienne kontaktowe)
  • “id_numbers” – wymaga kolumny z funkcją “DANE_OGOLNE” lub co najmniej jednej kolumn z funkcją osób/firm (zmienne osób/firm)

ConfigDeduplication

Zmienna Typ Opis
on Boolean Określa czy dla pliku wejściowego ma być wykonana deduplikacja rekordów.
incremental Boolean Określa czy deduplikacja rekordów powinna odbywać się uwzględniając zawartość innych plików przesłanych z opcją incremental.

{

“on”: 0,
“incremental”: 0

}

 

ConfigClient

Zmienna Typ Opis
name String Nazwa konfiguracji przygotowywanej na życzenie klienta, którą należy wykorzystać.
mode String Kolejny poziom określający w jakim trybie powinno być uruchomione DQ dla danego klienta.

{

“name”: “nazwa klienta”,
“mode”: “”

}

 

JobReport

Zmienna Typ Opis
results JobReportResults Obiekt zagnieżdżony JobReportResults.
quality_issues Array Pole obecnie nie wykorzystywane.
quality_names JobReportQualityNames Obiekt zagnieżdżony JobReportQualityNames.

{

“results”: JobReportResults,
“quality_issues”: [],
“quality_names”: JobReportQualityNames

}

 

JobReportResults

Zmienna Typ Opis
status String Status mówiący o tym na jakim etapie procesowania znajduje się zadanie. Możliwe statusy zostały wymienione w opisie metody POBIERANIE STATUSU ZADANIA.
error_description String Opis błędu, jeśli wystąpił w trakcie przetwarzania pliku.
input Number Liczba rekordów w pliku wejściowym.
succeed Number Liczba rekordów przetworzonych prawidłowo.
succeed_value Number Liczba rekordów przetworzonych prawidłowo.
failed Number Liczba rekordów pominiętych z powodu błędów.
level_town Number Liczba rekordów dopasowanych do poziomu miasta.
level_street Number Liczba rekordów dopasowanych do poziomu ulicy.
level_building Number Liczba rekordów dopasowanych do poziomu budynku.
level_premises Number Liczba rekordów dopasowanych do poziomu lokalu.

{

“status”: “OK”,
“error_description”: “”,
“input”: 0,
“succeed”: 1,
“succeed_value”: 1,
“failed”: 0,
“level_town”: 0,
“level_street”: 0,
“level_building”: 0,
“level_premises”: 0

}

 

JobReportQualityNames

Obecnie obiekt nie jest wykorzystywany, a wszystkie pola przyjmują wartość 0.

{

“names_ok”: 0,
“surnames_ok”: 0,
“companies_ok”: 0,
“names_failed”: 0,
“surnames_failed”: 0

}

 

AccountStatus

Zmienna Typ Opis
email String E-mail użytkownika.
balance Number Stan konta.
credit Number Kredyt przydzielony dla konta.
total_records Number Liczba wszystkich przeczyszczonych rekordów.

{

“email”: “test2@3e.pl”,
“balance”: 1000,
“credit”: 0,
“total_records”: 100

}

 

JobStatus

Zmienna Typ Opis
job_id String Unikalny identyfikator zadania nadawany przez aplikację DQ Batch.
status String Status mówiący o tym na jakim etapie procesowania znajduje się zadanie. Możliwe statusy zostały wymienione w opisie metody POBIERANIE STATUSU ZADANIA.

{

“job_id”: “b7432604-492b-42cc-a45b-cf7eec09b7c1”,
“status”: “EXECUTION”

}