RUIAN API

Registr RUIAN je užitečná věc. Ale připojit se na něj obnáší prokousat se nehoráznými stohy dokumentace.

A co za to dostanete?

SOAP rozhraní… 👎

Protože máme raději REST (JSON over HTTP) než SOAP, vyřešili jsme si to po svém. Data RUIANu jsou naštěstí volně ke stažení a jsme tak malá zemička, že se všechny naše adresy dají obsluhovat in-memory. A když už to máme, proč se nerozdělit. Představujeme:

https://ruian.fnx.io/

Validator

Jednou ze dvou cest jak API využít je validátor adres. Pošlete nám adresu, kterou vám uživatel vyplnil, a my vám potrvdíme, jestli adresa existuje. Nebo najdeme takovou, která by to mohla být.

validate

Služba validate se pokusí zadanou adresu najít v registru. Když se to nepodaří, pokusí se najít vhodného kandidáta (možná překlep v ulici, nebo názvu obce, části obce, možná jsou přehozená čísla orientační a popisná…).

GET request

curl https://ruian.fnx.io/api/v1/ruian/validate?apiKey={apiKey}&municipalityName={municipalityName}&zip={zip}&cp={cp}&street={streetName}

Parametry

  • apiKey – API klíč
  • municipalityId – přesné RUIAN id obce, znáte-li
  • municipalityName – název obce
  • municipalityPartName – název části obce
  • municipalityPartId – přesné RUIAN id části obce, znáte-li
  • zip – PSČ
  • ce – číslo evidenční.
  • co – číslo orientační
  • cp – číslo popisné
  • street – název ulice nebo části obce
  • ruianId – id adresy v RUIANu (pokud uvedete tento parametr, všechny ostatní se ignorují)

Odpověď

Jako odpověd dostanete JSON podobný tomuto:

{
    "status": "POSSIBLE",
    "message": null,
    "place": {
        "confidence": 0.9413223140495868,
        "municipalityId": 546801,
        "municipalityName": "Nová Včelnice",
        "municipalityPartId": 86754,
        "municipalityPartName": "Chlum",
        "streetName": "Zámecká",
        "ce": null,
        "cp": "2",
        "co": null,
        "zip": 37842,
        "id": 546801,
        "ruianId": 546801
    }
}
demo

Status

  • "ERROR" – Chyba v datech dotazu.
  • "NOT_FOUND" – Nenalezena žádná data.
  • "POSSIBLE" – Shoda s malou odchylkou.
  • "MATCH" – Shoda.

Message

Popis stavu nebo chyby.

Place

  • confidence – Přesnost shody nalezeného místa.
  • municipalityId – ID obce.
  • municipalityName – Název obce.
  • municipalityPartId – ID části obce.
  • municipalityPartName – Název části obce.
  • streetName – Název ulice nebo části obce.
  • ce – Číslo evidenční.
  • cp – Číslo popisné.
  • co – Číslo orientační.
  • id – ID adresy v RUIAN
  • ruianId – stejné ID
  • zip – PSČ.

HTTP kód

  • 200 – OK.
  • 401 – Špatný API klíč.
  • 422 – Chybějící parametry.
  • 429 – Překročen limit requestů.
  • 500 – Interní chyba serveru.

Builder

Druhou z cest jak API využít je builder adres. Postupně se dotazujte na region, obec, ulici a místo a ke konci získáte všechny informace o daném místě.

regions

GET request

curl https://ruian.fnx.io/api/v1/ruian/build/regions?apiKey={apiKey}

Parametry

  • apiKey – API klíč

Odpověď

Jako odpověd dostanete JSON podobný tomuto:

{
    "data": [
        {
            "regionId": "CZ010",
            "regionName": "Hlavní město Praha"
        },
        {
            "regionId": "CZ020",
            "regionName": "Středočeský kraj"
        }
    ]
}
demo

Data

  • regionId – kód kraje.
  • regionName – Název kraje.

HTTP kód

  • 200 – OK.
  • 401 – Špatný API klíč.
  • 422 – Chybějící parametry.
  • 429 – Překročen limit requestů.
  • 500 – Interní chyba serveru.

municipaties

GET request

curl https://ruian.fnx.io/api/v1/ruian/build/municipalities?apiKey={apiKey}&regionId={regionId}

Parametry

  • apiKey – API klíč
  • regionId – kód kraje

Odpověď

Jako odpověd dostanete JSON podobný tomuto:

{
    "data": [
        {
            "municipalityId": 561631,
            "municipalityName": "Jablonné v Podještědí"
        },
        {
            "municipalityId": 513890,
            "municipalityName": "Skalka u Doks"
        }
    ]
}
demo

Data

  • municipalityId – kód obce.
  • municipalityName – Název obce.

HTTP kód

  • 200 – OK.
  • 401 – Špatný API klíč.
  • 422 – Chybějící parametry.
  • 429 – Překročen limit requestů.
  • 500 – Interní chyba serveru.

streets

GET request

curl https://ruian.fnx.io/api/v1/ruian/build/streets?apiKey={apiKey}&municipalityId={municipalityId}

Parametry

  • apiKey – API klíč
  • municipalityId – kód obce

Odpověď

Jako odpověd dostanete JSON podobný tomuto:

{
    "data": [
        {
            "streetName": "Liberecká"
        },
        {
            "streetName": "Pod Špičákem"
        },
        {
            "streetLessPartName": "Větrov"
        }
    ]
}
demo

Data

  • streetName – Název ulice.
  • streetLessPartName – Název části obce.

HTTP kód

  • 200 – OK.
  • 401 – Špatný API klíč.
  • 422 – Chybějící parametry.
  • 429 – Překročen limit requestů.
  • 500 – Interní chyba serveru.

places

GET request

curl https://ruian.fnx.io/api/v1/ruian/build/places?apiKey={apiKey}&municipalityId={municipalityId}&streetName={streetName}

Parametry

  • apiKey – API klíč
  • municipalityId – kód obce
  • streetName – název ulice nebo název části obce

Odpověď

Jako odpověd dostanete JSON podobný tomuto:

{
    "data": [
        {
            "placeCe": null,
            "placeCp": "2",
            "placeCo": null,
            "placeZip": 47001,
            "placeId": 23451891
        },
        {
            "placeCe": null,
            "placeCp": "3",
            "placeCo": null,
            "placeZip": 47001,
            "placeId": 23451904
        }
    ]
}
demo

Data

  • placeCe – Číslo evidenční.
  • placeCp – Číslo popisné.
  • placeCo – Číslo orientační.
  • placeZip – PSČ.
  • placeId – kód místa.

HTTP kód

  • 200 – OK.
  • 401 – Špatný API klíč.
  • 422 – Chybějící parametry.
  • 429 – Překročen limit requestů.
  • 500 – Interní chyba serveru.

Užívání

API můžete používat libovolně do 1000 requestů za hodinu. Ovšem nemůžeme vám garantovat žádné SLA, správnost dat… Budete používat stejnou službu jako používáme my, takže se budeme snažit jí udržet v chodu, ale slíbit vám nemůžeme nic.

Pokud garance potřebujete, ozvěte se nám, určitě nějakou cestu najdeme: info@fnx.io.

Abyste mohli naše API používat, musíme vám vygenerovat API klíč, který vám pošleme na email. Váš email potřebujeme proto, abychom vás mohli kontaktovat, pokud by se nám zdálo, že službu zneužíváte, přetěžujete apod.