API Dokumentáció

Minden kéréshez szükséges az X-Api-Key fejléc. Az API base URL: https://api.kozterulet-api.hu/api/v1

Hitelesítés

Minden API kéréshez szükséges egy érvényes API kulcs, amelyet az X-Api-Key HTTP fejlécben kell elküldeni. Az API kulcsot a regisztráció után a felhasználói fiókban találod.

curl -X POST https://api.kozterulet-api.hu/api/v1/streets/search \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your_api_key_here" \
  -d '{ "city": "Budapest" }'

Lapozás és rendezés

A keresési és polygon végpontok lapozott választ adnak vissza. Paraméterek:

Mező	Típus	Leírás
`page`	integer	Oldalszám (0-tól indul, alapértelmezett: 0)
`size`	integer	Oldal méret (alapértelmezett: 20, minimum: 5)
`sorts`	array	Rendezés: `[{ "key": "name", "direction": "ASC" }]`

Megyék listázása

GET/counties

Visszaadja az összes magyar megye listáját, ábécé sorrendben. Nincs lapozás — mindig a teljes lista érkezik.

Válasz
[
  {
    "name": "Baranya"
  },
  {
    "name": "Borsod-Abaúj-Zemplén"
  },
  {
    "name": "Budapest"
  },
  {
    "name": "Pest"
  }
]

Városkeresés

POST/cities/search

Városok keresése egy adott megyén belül. Támogatja az előtag-alapú automatikus kiegészítést a város nevére. Lapozott eredmények.

Kérés paraméterek

Mező	Típus	Kötelező	Leírás
`county`	string	igen	Megye neve
`namePrefix`	string	nem	Városnév előtag (autocomplete)

Kérés
{
  "county": "Pest",
  "namePrefix": "Bud",
  "page": 0,
  "size": 20
}

Válasz
{
  "content": [
    {
      "name": "Budajenő",
      "county": "Pest"
    },
    {
      "name": "Budakalász",
      "county": "Pest"
    },
    {
      "name": "Budakeszi",
      "county": "Pest"
    },
    {
      "name": "Budaörs",
      "county": "Pest"
    }
  ],
  "totalElements": 4,
  "totalPages": 1,
  "size": 20,
  "number": 0
}

Irányítószám keresés

POST/postal-codes/search

Irányítószámok keresése megyén belül, opcionálisan város szerinti szűréssel. Lapozott eredmények.

Kérés paraméterek

Mező	Típus	Kötelező	Leírás
`county`	string	igen	Megye neve
`city`	string	nem	Város neve (opcionális szűrő)

Kérés
{
  "county": "Budapest",
  "city": "Budapest",
  "page": 0,
  "size": 10
}

Válasz
{
  "content": [
    {
      "code": "1007",
      "city": "Budapest",
      "county": "Budapest"
    },
    {
      "code": "1011",
      "city": "Budapest",
      "county": "Budapest"
    },
    {
      "code": "1012",
      "city": "Budapest",
      "county": "Budapest"
    }
  ],
  "totalElements": 163,
  "totalPages": 17,
  "size": 10,
  "number": 0
}

Utcák keresése

POST/streets/search

Teljes szövegű utcakeresés automatikus kiegészítéssel. Lapozott eredménylista várossal, irányítószámmal és kerülettel.

Kérés paraméterek

Mező	Típus	Kötelező	Leírás
`city`	string	igen	Város neve
`streetPrefix`	string	nem	Utcanév előtag (autocomplete)
`type`	string	nem	Közterület típus (utca, tér, körút, stb.)
`postalCode`	string	nem	Irányítószám
`settlementPart`	string	nem	Településrész / kerület

Kérés
{
  "city": "Budapest",
  "streetPrefix": "Kossuth",
  "page": 0,
  "size": 20
}

Válasz
{
  "content": [
    {
      "country": "HU",
      "county": "Budapest",
      "city": "Budapest",
      "settlementPart": "V. kerület",
      "postalCode": "1055",
      "streetName": "Kossuth Lajos",
      "streetType": "tér",
      "fullStreetName": "Kossuth Lajos tér",
      "displayName": "1055 Budapest Kossuth Lajos tér"
    },
    {
      "country": "HU",
      "county": "Budapest",
      "city": "Budapest",
      "settlementPart": "V. kerület",
      "postalCode": "1053",
      "streetName": "Kossuth Lajos",
      "streetType": "utca",
      "fullStreetName": "Kossuth Lajos utca",
      "displayName": "1053 Budapest Kossuth Lajos utca"
    }
  ],
  "totalElements": 27,
  "totalPages": 2,
  "size": 20,
  "number": 0
}

Utca validálás

POST/streets/validate

Ellenőrzi, hogy a megadott utca létezik-e. Boolean eredményt ad vissza HTTP 404 helyett.

Kérés paraméterek

Mező	Típus	Kötelező	Leírás
`city`	string	igen	Város neve
`streetName`	string	igen	Utca neve
`type`	string	igen	Közterület típus
`postalCode`	string	nem	Irányítószám
`settlementPart`	string	nem	Településrész / kerület

Kérés
{
  "city": "Budapest",
  "streetName": "Kossuth Lajos",
  "type": "utca"
}

Válasz
{
  "exists": true
}

Területi keresés (Polygon)

POST/streets/polygon-search

Térbeli keresés, amely visszaadja az adott poligonon belüli utcákat. A poligon [hosszúság, szélesség] koordináta-párok listája (WGS84 / EPSG:4326). Minimum 3 pont szükséges. A poligon automatikusan záródik, ha az első és utolsó pont eltér. A poligon maximális területe 50 km² — az ennél nagyobb területre vonatkozó kérések 400 Bad Request választ kapnak.

Kérés paraméterek

Mező	Típus	Kötelező	Leírás
`polygon`	array	igen	Koordináta-párok listája: `[[lng, lat], ...]`

Kérés
{
  "polygon": [
    [
      19.05,
      47.5
    ],
    [
      19.06,
      47.5
    ],
    [
      19.06,
      47.51
    ],
    [
      19.05,
      47.51
    ]
  ],
  "page": 0,
  "size": 20
}

Válasz
{
  "content": [
    {
      "country": "HU",
      "county": "Budapest",
      "city": "Budapest",
      "settlementPart": "V. kerület",
      "postalCode": "1054",
      "streetName": "Alkotmány",
      "streetType": "utca",
      "fullStreetName": "Alkotmány utca",
      "displayName": "1054 Budapest Alkotmány utca"
    }
  ],
  "totalElements": 63,
  "totalPages": 4,
  "size": 20,
  "number": 0
}

Utcák irányítószám alapján

POST/streets/by-postal-code

Visszaadja az adott irányítószámhoz tartozó összes utcát. Lapozott eredmények teljes utcaadatokkal.

Kérés paraméterek

Mező	Típus	Kötelező	Leírás
`postalCode`	string	igen	Irányítószám

Kérés
{
  "postalCode": "1052",
  "page": 0,
  "size": 10
}

Válasz
{
  "content": [
    {
      "country": "HU",
      "county": "Budapest",
      "city": "Budapest",
      "settlementPart": "V. kerület",
      "postalCode": "1052",
      "streetName": "Aranykéz",
      "streetType": "utca",
      "fullStreetName": "Aranykéz utca",
      "displayName": "1052 Budapest Aranykéz utca"
    }
  ],
  "totalElements": 33,
  "totalPages": 4,
  "size": 10,
  "number": 0
}

Közterület típusok

GET/streets/types

Visszaadja az összes különböző közterület típust (utca, tér, körút, stb.), ábécé sorrendben. Nincs lapozás — mindig a teljes lista érkezik.

Válasz
[
  "dűlő",
  "fasor",
  "körút",
  "köz",
  "lépcső",
  "park",
  "sétány",
  "sor",
  "sugárút",
  "tér",
  "udvar",
  "utca",
  "út"
]

Válasz mezők

Az utcakeresés és polygon keresés eredményeiben az alábbi mezők szerepelnek:

Mező	Típus	Leírás
`country`	string	Országkód (mindig "HU")
`county`	string	Megye neve
`city`	string	Város neve
`settlementPart`	string	Településrész / kerület
`postalCode`	string	Irányítószám
`streetName`	string	Utca neve
`streetType`	string	Közterület típus
`fullStreetName`	string	Teljes utcanév (név + típus)
`displayName`	string	Megjelenítési név (irányítószám + város + utca)

Hibakezelés

Az API RFC 9457 (Problem Details) formátumban adja vissza a hibákat.

HTTP kód	Leírás
`400`	Érvénytelen kérés (hiányzó kötelező mezők, hibás formátum)
`401`	Hiányzó API kulcs
`403`	Érvénytelen vagy lejárt API kulcs
`429`	Túllépte a kéréskorlátot (rate limit)
`500`	Szerverhiba

400 — Hibás kérés
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "city: must not be blank",
  "instance": "/api/v1/streets/search"
}

401 — Hiányzó kulcs
{
  "type": "about:blank",
  "title": "Missing API Key",
  "status": 401,
  "detail": "X-Api-Key header is required",
  "instance": "/api/v1/streets/search"
}

Kéréskorlát (Rate Limit)

Minden válasz tartalmaz egy X-Rate-Limit-Remaining fejlécet, amely jelzi a hátralévő kérések számát.

Csomag	Kérés/mp	Burst
Free	5	10
Starter	20	40
Growth	100	200

OpenAPI specifikáció

Az API teljes OpenAPI 3.1 specifikációja letölthető JSON formátumban. Használható kliens SDK generáláshoz, Postman importáláshoz, vagy bármilyen OpenAPI-kompatibilis eszközzel.

OpenAPI JSON letöltése

Adatforrások

Az API adatai részben az © OpenStreetMap közreműködőitől származnak, az Open Data Commons Open Database License (ODbL) 1.0 licenc alapján.