teryt24.pl

teryt24.pl · Dokumentacja API

Masowa walidacja adresów z CSV

POST /v1/bulk/addresses wgrywa plik CSV z adresami i zwraca zadanie (202): plik jest przetwarzany w tle, wiersz po wierszu, przez TEN SAM potok walidacji, który działa w GET /v1/validate. Kolumny nazywa klient (parametry zapytania) — usługa NIGDY nie zgaduje, która kolumna to ulica. Klucz API jest WYMAGANY (401 bez niego): zadanie przechowuje dane osobowe klienta na instancji przez czas retencji i kosztuje realny czas pracy.

Plik wynikowy zawiera kolumny klienta BEZ ZMIAN, obok nich kolumny usługi: potwierdzoną miejscowość, ulicę, numer, kod pocztowy i współrzędne, ocenę dopasowania każdego pola oraz powody, dla których wiersze niepotwierdzone nie zostały potwierdzone. Wartość, której rejestr nie potwierdził, zostaje PUSTA — nigdy zgadnięta. Wiersze dzielą się na cztery grupy: matched, ambiguous, invalid i unmatched.

Wgranie tego samego pliku (albo tego samego nagłówka Idempotency-Key) zwraca ISTNIEJĄCE zadanie zamiast przetwarzać i naliczać je drugi raz. Wgrany plik i jego wynik są usuwane po zakończeniu okresu retencji (domyślnie 24 godziny), a zadanie odpowiada wtedy 410 Gone.

POST /v1/bulk/addresses

Wgranie pliku (jego treść JEST ciałem żądania, typ text/csv) i wskazanie kolumn. Odpowiedź 202 z uchwytem zadania.

NazwaWymaganyOpis
locality—The column holding the locality — a name or a 7-digit SYM. Required unless `address` is given.
street—The column holding the street — a name or a 5-digit SYM_UL.
number—The column holding the house number.
postalCode—The column holding the postal code — it also narrows an ambiguous locality name.
address—The column holding the WHOLE address (one free-text field) — the alternative to the four separate columns.
id—The column identifying the row (echoed into the result).

Treść żądania (JSON)

NazwaWymagany/typOpis
<treść żądania>CSV (text/csv)Plik z nagłówkiem. UTF-8 (BOM w porządku), separator przecinek, średnik lub tabulator.

Przykład

Wgranie pliku

curl -X POST "https://teryt24.pl/v1/bulk/addresses?locality=miejscowosc&ulica=ulica&numer=nr&kod=kod&id=id" \
  -H "Content-Type: application/json" \
  -d 'id,miejscowosc,ulica,nr,kod
1,Wrocław,ul. Legnicka,61,53-331
2,Wrocław,ul. Legnicka,62,53-331'
id,miejscowosc,ulica,nr,kod
1,Wrocław,ul. Legnicka,61,53-331
2,Wrocław,ul. Legnicka,62,53-331

Odpowiedź:

{
  "id": "0f3c1b7e-2f5a-4a1e-9c2d-6b1a2f0d4e11",
  "status": "queued",
  "filename": "adresy.csv",
  "rows": 2,
  "processed": 0,
  "matched": 0,
  "ambiguous": 0,
  "invalid": 0,
  "unmatched": 0,
  "error": null,
  "resultUrl": null
}
StatusOpis
200The same file was uploaded before: the EXISTING job is returned (`duplicate: true`) — the file is not processed or billed twice.
202The job was accepted: `{ id, status, rows, processed, matched, ambiguous, invalid, unmatched, resultUrl }`. Poll GET /v1/bulk/jobs/{id} for progress and GET /v1/bulk/jobs/{id}/result.csv for the result.
400Invalid query parameters.
401A named API key is required for bulk processing.
413The file has more rows than the configured limit.
429Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds.
500Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic — error detail lives in the server logs, never in the response.

GET /v1/bulk/jobs/{id}

Stan zadania i postęp: ile wierszy przetworzono i jak się dzieli (matched / ambiguous / invalid / unmatched).

Sprawdź na żywo: /v1/bulk/jobs/0f3c1b7e-2f5a-4a1e-9c2d-6b1a2f0d4e11

NazwaWymaganyOpis
id path✓The job id.

Przykład

Zadanie po zakończeniu

curl "https://teryt24.pl/v1/bulk/jobs/0f3c1b7e-2f5a-4a1e-9c2d-6b1a2f0d4e11"

Odpowiedź:

{
  "id": "0f3c1b7e-2f5a-4a1e-9c2d-6b1a2f0d4e11",
  "status": "done",
  "rows": 2,
  "processed": 2,
  "matched": 1,
  "ambiguous": 0,
  "invalid": 0,
  "unmatched": 1,
  "resultUrl": "/v1/bulk/jobs/0f3c1b7e-2f5a-4a1e-9c2d-6b1a2f0d4e11/result.csv"
}
StatusOpis
200The job's state.
401A named API key is required.
404No such job (for this key).
410The job's files were deleted when the retention window ended.
429Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds.

GET /v1/bulk/jobs/{id}/result.csv

Plik wynikowy: kolumny klienta bez zmian + kolumny usługi. 409, gdy zadanie jeszcze trwa; 410, gdy pliki zostały usunięte.

Sprawdź na żywo: /v1/bulk/jobs/0f3c1b7e-2f5a-4a1e-9c2d-6b1a2f0d4e11/result.csv

NazwaWymaganyOpis
id path✓The job id.

Przykład

Wiersz wyniku (skrócony)

curl "https://teryt24.pl/v1/bulk/jobs/0f3c1b7e-2f5a-4a1e-9c2d-6b1a2f0d4e11/result.csv"

Odpowiedź (skrócona — pokazano pierwsze wiersze):

"id","miejscowosc","ulica","nr","kod","teryt24_status","teryt24_verdict","teryt24_locality","teryt24_locality_sym","teryt24_street","teryt24_street_id","teryt24_house_number","teryt24_postal_code","teryt24_lat","teryt24_lon","teryt24_match","teryt24_issues"
"1","Wrocław","ul. Legnicka","61","53-331","matched","valid","Wrocław","0983988","ul. Legnicka","12400","61","53-331","50.7322","16.6403","locality=exact;street=exact;houseNumber=exact;postalCode=exact",""
StatusOpis
200The result file.
401A named API key is required.
404No such job (for this key).
409The job has not finished yet.
410The job's files were deleted when the retention window ended.
429Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds.

Przeglądaj dane

Te same dane mają strony w przeglądarce — karty miejscowości, ulic i kodów pocztowych:

Wrocławul. Legnicka53-331

Powiązane endpointy

Przewodnik integracjiWalidacja adresu w jednym zapytaniuGeokodowanie i walidacja adresówLimity, klucze i identyfikacja

Wszystkie endpointy /v1 zwracają JSON, obsługują CORS i są objęte dokumentem openapi.json. Interaktywna wersja tej referencji: /docs.

Limity: 60 zapytań/min na IP bez klucza; klucz API (nagłówek X-API-Key) dostaje własny kubełek. Po przekroczeniu endpointy odpowiadają HTTP 429 z nagłówkiem Retry-After. Szczegóły: limity i klucze · zasady użycia.

Atrybucja jest warunkiem użycia. Wyświetlając wyniki w aplikacji, stronie, mapie lub raporcie, pokaż: Dane: GUS TERYT, punkty adresowe PRG (GUGiK), kody pocztowe GeoNames — przez teryt24.pl z linkiem do zasad użycia. Użycie wyłącznie po stronie serwera jest zwolnione.