GeoAdrese API. Dokumentacija i primjeri.

Autentikacija

Otvorite FREE račun: email → potvrda → dashboard → API ključ → prvi request. Ključ se prikazuje samo jednom; spremite ga. Bez kartice i ručnog odobrenja.

Osnovni URL je https://api.geoadrese.net. Svaki /v1 endpoint zahtijeva zaglavlje X-API-Key. Ključ čuvajte na backendu, izvan browsera i mobilne aplikacije. CORS za izravne klijentske pozive nije omogućen.

Isprobajte bez vlastitog ključa u Tražilici; svaki rezultat nudi „Pogledaj API poziv“ s primjerom za vaš backend.

curl --get 'https://api.geoadrese.net/v1/search' \
  --header "X-API-Key: $GEOADRESE_API_KEY" \
  --data-urlencode 'q=vukovarska 5 zagreb' \
  --data 'limit=1'

Endpointi

Preuzmite OpenAPI 3.1 specifikaciju za strojno čitljiv ugovor.

GET /health je javna provjera rada bez ključa. Skupni batch endpoint ne postoji.

Parametri

qobavezno

Search: 1–250 znakova. Autocomplete: 3–250 znakova. Unos se normalizira na Unicode NFC; rubni i ponovljeni razmaci uklanjaju se.

limitneobavezno

Search: 1–50, zadano 10. Autocomplete: 1–10, zadano 5.

idputanja

DGU identifikator, npr. KB.0022073018. Ukinuta adresa može vratiti 404.

Nepoznat ili ponovljen parametar vraća 400 invalid_parameter.

GET /v1/autocomplete?q=Vukovars&limit=3
X-API-Key: YOUR_API_KEY

Odgovori i podudarnost

{
  "data": [
    {
      "id": "KB.0022073018",
      "label": "Ulica grada Vukovara 5, 10110 Zagreb",
      "street": "Ulica grada Vukovara",
      "houseNumber": "5",
      "settlement": "Zagreb",
      "municipality": null,
      "postalCode": "10110",
      "lat": 45.7995066,
      "lon": 15.9569118,
      "match": {
        "type": "fuzzy",
        "score": 0.95
      }
    }
  ],
  "meta": {
    "count": 1
  }
}

Search i autocomplete vraćaju data kao niz. Dohvat po ID-u vraća { "data": { … } }. Nedostajuće vrijednosti su null; municipality zasad je null.

exact

Točan pogodak prema pravilima endpointa. Na autocompleteu može označavati prefiks.

fuzzy

Približan pogodak: tipfeler, drugi oblik ili nepotpun naziv. Pregledajte pronađenu adresu.

partial

Rezultat za provjeru, primjerice razlika u kućnom broju ili nepotpun upit.

Score je relativna ocjena 0–1, ne statistička vjerojatnost. Za obradu neurednih zapisa koristite resolve statuse opisane u nastavku. Search i autocomplete ostaju odvojeni od resolve odluke. Kućni i poštanski broj ne ispravljaju se tiho.

Normalizacije i provenance

Opcionalno polje match.provenance u search, autocomplete i resolve odgovoru opisuje primijenjene normalizacije. Sadrži schemaVersion: 1 i niz normalizations; kod doslovnog podudaranja može izostati. Kanonska DGU adresa ostaje nepromijenjena.

{
  "schemaVersion": 1,
  "normalizations": [
    "curated-alias"
  ]
}

curated-alias

Provjereni lokalni naziv, npr. Jelačić plac, Stradun, Kalelarga, Riva ili Tomislavac. Dvosmisleni nazivi traže dopušten grad ili poštanski broj.

place-case

Mjesto u padežu, npr. „u Zagrebu“ umjesto „Zagreb“.

street-number

Broj u nazivu ulice, npr. „27. Februara“ ili rimski zapis „XXVII.“. Ovo se ne odnosi na ispravljanje kućnog broja.

ordered-initials

Inicijali imena u nazivu ulice, npr. „A. G. Matoša“, uz očuvan redoslijed.

bilingual-official

Podudaranje s dvojezičnim službenim nazivom u DGU podacima.

Provenance objašnjava kako je upit protumačen; nije dodatna ocjena sigurnosti. Za odluku o automatskom prihvatu provjerite resolve status, confidence i kanonsku adresu.

Resolve: normalizacija adresa

POST /v1/resolve prihvaća samo JSON polje address, najviše 250 Unicode znakova i tijelo do 8 KB. Normalizira rubne i ponovljene razmake te Unicode NFC.

POST /v1/resolve
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{"address":"vlasska 10 zagreb"}

{
  "data": {
    "status": "matched",
    "input": "vlasska 10 zagreb",
    "canonical": {
      "id": "KB.0022075340",
      "label": "Vlaška ulica 10, 10000 Zagreb",
      "street": "Vlaška ulica",
      "houseNumber": "10",
      "settlement": "Zagreb",
      "municipality": null,
      "postalCode": "10000",
      "lat": 45.8135437,
      "lon": 15.9793051
    },
    "match": {
      "type": "fuzzy",
      "score": 0.94,
      "confidence": "high",
      "fields": {
        "street": 0.9,
        "houseNumber": 1,
        "place": 1
      }
    },
    "alternatives": []
  }
}

matched

Jedna kanonska adresa prema pravilima podudarnosti.

ambiguous

Prijedlog nije za automatski prihvat. Provjerite canonical i alternatives; više adresa može odgovarati unosu.

no_match

Nema upotrebljivog kandidata: canonical i match su null, alternatives je prazan niz. Odgovor je HTTP 200 i troši jedan upit.

Match sadrži type, score, confidence i fields za street, houseNumber i place te opcionalni provenance. Confidence je heuristička kategorija high/medium/low, a ne kalibrirana vjerojatnost.

Rezultat dobiven kolokvijalnim aliasom, inicijalima, redno/rimskim ili službenim dvojezičnim oblikom najviše je fuzzy / medium, čak i kad je jednoznačan. Primjer „Jelačić plac 1, Zagreb“ vraća matched / medium. Pravilo koje prihvaća samo confidence === "high" takav će rezultat izdvojiti za pregled. Mjesto u padežu samo po sebi ne ograničava confidence na medium.

Ravnopravna konkurentska adresa s drugim DGU ID-jem spušta high na medium; postojeći low ostaje low. Resolve tada vraća ambiguous i konkurente u alternatives. Sam nedostatak grada ili kućnog broja ne snižava jednoznačan rezultat. Ni oznaka exact sama po sebi ne jamči jedinstvenu adresu.

Nearest: reverse geocoding

GET /v1/nearest zahtijeva konačne decimalne koordinate lat (−90 do 90) i lon (−180 do 180). Limit je 1–10, zadano 3; maxDistanceMeters je cijeli broj 1–200000, zadano 50000.

GET /v1/nearest?lat=45.8131&lon=15.9775&limit=1&maxDistanceMeters=250

{
  "data": [
    {
      "id": "KB.0022075307",
      "label": "Trg bana Josipa Jelačića 7, 10000 Zagreb",
      "street": "Trg bana Josipa Jelačića",
      "houseNumber": "7",
      "settlement": "Zagreb",
      "municipality": null,
      "postalCode": "10000",
      "lat": 45.8133182,
      "lon": 15.9776926,
      "distanceMeters": 28.5
    }
  ]
}

Data je niz kanonskih adresa s distanceMeters, poredan od najbliže prema udaljenijima. Udaljenost je u metrima, zaokružena na jednu decimalu. Nearest nema search match score. Prazan niz znači da nema adresa unutar radijusa i troši jedan upit.

Neispravna koordinata vraća 400 invalid_coordinate, a radijus 400 invalid_distance. Nepoznati i ponovljeni parametri se odbijaju.

Limiti i potrošnja

Limiti vrijede po accountu. Mjesečnu kvotu troše uspješni search, autocomplete, resolve, nearest i addresses pozivi, uključujući prazne rezultate i cache hitove. Greške i usage ne troše kvotu, ali usage podliježe limitu zahtjeva u sekundi.

Kvota se obnavlja početkom kalendarskog mjeseca po UTC-u. /v1/usage vraća period, used, limit, remaining i resetAt. Usporedite pakete.

Greške

Svaki odgovor nosi X-Request-ID. Sačuvajte ga ako trebate pomoć s konkretnim zahtjevom.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}

Izvor podataka

GeoAdrese koristi službeni DGU INSPIRE skup adresa. Broj adresa i datum DGU kataloga trenutačno nisu dostupni. Metapodaci su dostupni i kao javni JSON podataka o DGU skupu.

Nova verzija provjerava se svaku noć; podaci se preuzimaju kad DGU objavi novu verziju. Ukinute adrese uklanjaju se. GeoAdrese nije službeni servis DGU-a.