Poštové adresy

Prostredníctvom služby Swiftyper Places API je možné vyhľadať viacero druhov miest - adresu, ulicu, obec a poštové smerovacie číslo.

Definícia modelu

Atribúty

Name
place_id
Type
string
Description
Unikátny identifikátor miesta.
Name
highlight
Type
string
Description
Zvýraznená časť zhodná s dopytom vyhľadávania.
Name
formatted_address
Type
string
Description
Naformátovaná adresa miesta.
Name
street
Type
string
Description
Názov ulice.
Name
formatted_street
Type
string
Description
Naformátovaná ulica.
Name
street_number
Type
string
Description
Súpisné číslo.
Name
building_number
Type
string
Description
Orientačné číslo.
Name
formatted_number
Type
string
Description
Naformátované číslo ulice.
Name
postal_code
Type
string
Description
Poštové smerovacie číslo.
Name
municipality
Type
string
Description
Názov obce.
Name
district
Type
string
Description
Názov časti obce.
Name
county
Type
string
Description
Názov okresu.
Name
region
Type
string
Description
Názov kraju.
Name
latlng
Type
object
Description
Geokódovaná zemepisná šírka a dĺžka.
Name
latlng.lat
Type
double
Description
Name
latlng.lng
Type
double
Description
Name
object
Type
string
Description
Typ objektu, môže byť address, street, municipality, postal_code.
Name
formatted_country
Type
string
Description
Názov krajiny.
Name
country
Type
string
Description
Kód krajiny (dvojmiestny alfabetický kód ISO 3166).

POST/v1/places/query

Vyhľadanie adresy

Vyhľadanie poštových adries cez akúkoľvek časť adresy.

Povinné parametre

Name
query
Type
string
Description
Výraz vyhľadávania.
Name
api_key
Type
string
Description
Prístupový API kľúč môžete použiť ako parameter api_key alebo v hlavičke požiadavky X-Swiftyper-API-Key.

Parametre

Name
street
Type
string
Description
Výraz na upresnenie názvu a čísla ulice.
Name
municipality
Type
string
Description
Výraz na upresnenie názvu obce.
Name
postal_code
Type
string
Description
Výraz na upresnenie poštového smerovacieho čísla.
Name
context
Type
string[]
Description
Nastavenie oblastí pre vyhľadávanie (kľúč place_id). Výsledky vyhľadávania môžete odfiltrovať pre konkrétny kraj, okres alebo obec.
Name
contextType
Type
string
Description
Nastavenie typu vyhľadávacieho kontextu. Použite strict ak chcete vyhľadávať adresu s ďalšími zadanými parametrami (street, municipality alebo postal_code) alebo preference pokiaľ chcete adresy zo zadaného miesta uprednostniť.
Name
around_latlng
Type
string
Description
Prispôsobenie výsledkov vyhľadávania zadanej lokalite vo formáte latitude,longitude napr. 49.1992988,18.8211994.
Name
around_latlng_via_ip
Type
string
Description
Prispôsobenie výsledkov vyhľadávania aktuálnej lokalite používateľa.
Name
country
Type
string · obsahuje kód dostupnej krajiny
Description
Krajiny v ktorých sa adresa bude vyhľadávať.
Name
limit
Type
string
Description
Počet zobrazených výsledkov. Hodnota môže byť v rozmedzí 1 až 20. Predvolená hodnota je 7 výsledkov.

Výstup

Výstupom je množina údajov reprezentujúca objekt s popísanými atribútmi. V prípade chyby alebo nesprávnosti parametrov sa zobrazí chyba. Bežným zdrojom chýb je nezadanie API kľúču, alebo presiahnutie mesačného limitu na vyhľadávanie.

Požiadavka

curl -X POST https://api.swiftyper.sk/v1/places/query \
   -H 'X-Swiftyper-API-Key: 2SN360bLw7lI7KB9Awu5w8oYvCWv17bsA1NAboFNo01Y' \
   -d query=Ľudovíta Štúra \
   -d street="10"

Odpoveď

[
    {
        "place_id": "sk_gMmyS5861DBBOlA9j-MZsQ",
        "highlight": "<em>Ľ.</em> <em>Štúra</em> 107/<em>10</em>, 91401 Trenčianska Teplá, Slovenská republika",
        "formatted_address": "Ľ. Štúra 107/10, 91401 Trenčianska Teplá, Slovenská republika",
        "formatted_street": "Ľ. Štúra 107/10",
        "street_number": "107",
        "building_number": "10",
        "formatted_number": "107/10",
        "municipality": "Trenčianska Teplá",
        "postal_code": "91401",
        "street": "Ľ. Štúra",
        "region": "Trenčiansky kraj",
        "county": "Trenčín",
        "district": "Trenčianska Teplá",
        "latlng": {
            "lat": 48.93217044,
            "lng": 18.10914388
        },
        "object": "address",
        "formatted_country": "Slovenská republika",
        "country": "SK"
    },
    {
        "place_id": "sk_D72YztX4hh_8KVkY8VfGdQ",
        "highlight": "<em>Ľudovíta</em> <em>Štúra</em> 1043/<em>10</em>, 08501 Bardejov, Slovenská republika",
        "formatted_address": "Ľudovíta Štúra 1043/10, 08501 Bardejov, Slovenská republika",
        "formatted_street": "Ľudovíta Štúra 1043/10",
        "street_number": "1043",
        "building_number": "10",
        "formatted_number": "1043/10",
        "municipality": "Bardejov",
        "postal_code": "08501",
        "street": "Ľudovíta Štúra",
        "region": "Prešovský kraj",
        "county": "Bardejov",
        "district": "Bardejov",
        "latlng": {
            "lat": 49.30480275,
            "lng": 21.2803001
        },
        "object": "address",
        "formatted_country": "Slovenská republika",
        "country": "SK"
    },
    {...},
    {...}
]

POST/v1/places/street

Vyhľadanie ulice

Vyhľadanie ulíc na základe názvu.

Povinné parametre

Name
query
Type
string
Description
Výraz vyhľadávania.
Name
api_key
Type
string
Description
Prístupový API kľúč môžete použiť ako parameter api_key alebo v hlavičke požiadavky X-Swiftyper-API-Key.

Parametre

Name
municipality
Type
string
Description
Výraz na upresnenie názvu obce.
Name
context
Type
string[]
Description
Nastavenie oblastí pre vyhľadávanie (kľúč place_id). Výsledky vyhľadávania môžete odfiltrovať pre konkrétny kraj, okres alebo obec.
Name
contextType
Type
string
Description
Nastavenie typu vyhľadávacieho kontextu. Použite strict ak chcete vyhľadávať adresu s ďalšími zadanými parametrami (municipality) alebo preference pokiaľ chcete adresy zo zadaného miesta uprednostniť.
Name
around_latlng
Type
string
Description
Prispôsobenie výsledkov vyhľadávania zadanej lokalite vo formáte latitude,longitude napr. 49.1992988,18.8211994.
Name
around_latlng_via_ip
Type
string
Description
Prispôsobenie výsledkov vyhľadávania aktuálnej lokalite používateľa.
Name
country
Type
string · obsahuje kód dostupnej krajiny
Description
Krajiny v ktorých sa adresa bude vyhľadávať.
Name
limit
Type
string
Description
Počet zobrazených výsledkov. Hodnota môže byť v rozmedzí 1 až 20. Predvolená hodnota je 7 výsledkov.

Výstup

Požiadavka

curl -X POST https://api.swiftyper.sk/v1/places/street \
   -H 'X-Swiftyper-API-Key: 2SN360bLw7lI7KB9Awu5w8oYvCWv17bsA1NAboFNo01Y' \
   -d query=Beethoven

Odpoveď

[
    {
        "place_id": "sk_u6yEYf82daTjyfs3r0Dmbg",
        "highlight": "<em>Beethoven</em>ova",
        "street": "Beethovenova",
        "municipality": "Piešťany",
        "object": "street",
        "formatted_country": "Slovenská republika",
        "country": "SK"
    },
    {
        "place_id": "sk_crid0VwgyZ5l35sfq328NA",
        "highlight": "<em>Beethoven</em>ova",
        "street": "Beethovenova",
        "municipality": "Nitra",
        "object": "street",
        "formatted_country": "Slovenská republika",
        "country": "SK"
    },
    {
        "place_id": "cz_VobrHYk3JjcQEToxpg9koA",
        "highlight": "<em>Beethoven</em>ova",
        "street": "Beethovenova",
        "municipality": "Brno",
        "object": "street",
        "formatted_country": "Slovenská republika",
        "country": "SK"
    },
    {
        "place_id": "cz_UPav3iy_p9lDBQV-z7mQ3A",
        "highlight": "<em>Beethoven</em>ova",
        "street": "Beethovenova",
        "municipality": "Frýdek-Místek",
        "object": "street",
        "formatted_country": "Slovenská republika",
        "country": "SK"
    },
    {...},
    {...}
]

POST/v1/places/municipality

Vyhľadanie obce

Vyhľadanie obcí na základe názvu.

Povinné parametre

Name
query
Type
string
Description
Výraz vyhľadávania.
Name
api_key
Type
string
Description
Prístupový API kľúč môžete použiť ako parameter api_key alebo v hlavičke požiadavky X-Swiftyper-API-Key.

Parametre

Name
postal_code
Type
string
Description
Výraz na upresnenie poštového smerovacieho čísla.
Name
context
Type
string[]
Description
Nastavenie oblastí pre vyhľadávanie (kľúč place_id). Výsledky vyhľadávania môžete odfiltrovať pre konkrétny kraj, okres alebo obec.
Name
contextType
Type
string
Description
Nastavenie typu vyhľadávacieho kontextu. Použite strict ak chcete vyhľadávať adresu s ďalšími zadanými parametrami (postal_code) alebo preference pokiaľ chcete adresy zo zadaného miesta uprednostniť.
Name
around_latlng
Type
string
Description
Prispôsobenie výsledkov vyhľadávania zadanej lokalite vo formáte latitude,longitude napr. 49.1992988,18.8211994.
Name
around_latlng_via_ip
Type
string
Description
Prispôsobenie výsledkov vyhľadávania aktuálnej lokalite používateľa.
Name
country
Type
string · obsahuje kód dostupnej krajiny
Description
Krajiny v ktorých sa obec bude vyhľadávať.
Name
limit
Type
string
Description
Počet zobrazených výsledkov. Hodnota môže byť v rozmedzí 1 až 20. Predvolená hodnota je 7 výsledkov.

Výstup

Požiadavka

curl -X POST https://api.swiftyper.sk/v1/places/municipality \
   -H 'X-Swiftyper-API-Key: 2SN360bLw7lI7KB9Awu5w8oYvCWv17bsA1NAboFNo01Y' \
   -d query=Jabloň

Odpoveď

[
    {
        "place_id": "sk_yZ4uZvUW--uWo5REzGRTDg",
        "highlight": "<em>Jabloň</em> (Humenné, Slovenská republika)",
        "municipality": "Jabloň",
        "county": "Humenné",
        "region": "Prešovský kraj",
        "object": "municipality",
        "formatted_country": "Slovenská republika",
        "country": "SK"
    },
    {
        "place_id": "sk_ReIieZEL_M9ePv0DTKR4KQ",
        "highlight": "<em>Jabloň</em>ovce (Levice, Slovenská republika)",
        "municipality": "Jabloňovce",
        "county": "Levice",
        "region": "Nitriansky kraj",
        "object": "municipality",
        "formatted_country": "Slovenská republika",
        "country": "SK"
    },
    {
        "place_id": "cz_DNe3xu2pGe-JSriIQ8JzCA",
        "highlight": "<em>Jablon</em>ná (Příbram, Česká republika)",
        "municipality": "Jablonná",
        "county": "Příbram",
        "region": "Stredočeský kraj",
        "object": "municipality",
        "formatted_country": "Česká republika",
        "country": "CZ"
    },
    {
        "place_id": "cz_97gMCK2gJyyQVdzJo2bg9A",
        "highlight": "<em>Jablon</em>né v Podještědí (Liberec, Česká republika)",
        "municipality": "Jablonné v Podještědí",
        "county": "Liberec",
        "region": "Liberecký kraj",
        "object": "municipality",
        "formatted_country": "Česká republika",
        "country": "CZ"
    },
    {...},
    {...}
]

POST/v1/places/postal

Vyhľadanie PSČ

Vyhľadanie poštového smerovacieho čísla na základe kódu.

Povinné parametre

Name
query
Type
string
Description
Výraz vyhľadávania.
Name
api_key
Type
string
Description
Prístupový API kľúč môžete použiť ako parameter api_key alebo v hlavičke požiadavky X-Swiftyper-API-Key.

Parametre

Name
municipality
Type
string
Description
Výraz na upresnenie názvu obce.
Name
context
Type
string[]
Description
Nastavenie oblastí pre vyhľadávanie (kľúč place_id). Výsledky vyhľadávania môžete odfiltrovať pre konkrétny kraj, okres alebo obec.
Name
contextType
Type
string
Description
Nastavenie typu vyhľadávacieho kontextu. Použite strict ak chcete vyhľadávať adresu s ďalšími zadanými parametrami (municipality) alebo preference pokiaľ chcete adresy zo zadaného miesta uprednostniť.
Name
around_latlng
Type
string
Description
Prispôsobenie výsledkov vyhľadávania zadanej lokalite vo formáte latitude,longitude napr. 49.1992988,18.8211994.
Name
around_latlng_via_ip
Type
string
Description
Prispôsobenie výsledkov vyhľadávania aktuálnej lokalite používateľa.
Name
country
Type
string · obsahuje kód dostupnej krajiny
Description
Krajiny v ktorých sa PSČ bude vyhľadávať.
Name
limit
Type
string
Description
Počet zobrazených výsledkov. Hodnota môže byť v rozmedzí 1 až 20. Predvolená hodnota je 7 výsledkov.

Výstup

Požiadavka

curl -X POST https://api.swiftyper.sk/v1/places/postal \
   -H 'X-Swiftyper-API-Key: 2SN360bLw7lI7KB9Awu5w8oYvCWv17bsA1NAboFNo01Y' \
   -d query="01004"

Odpoveď

[
    {
        "place_id": "sk_C5Yd8zdpJaPzEBqJWi-KgQ",
        "highlight": "<em>01004</em>, Žilina",
        "postal_code": "01004",
        "municipality": "Žilina",
        "object": "postal_code",
        "formatted_country": "Slovenská republika",
        "country": "SK"
    },
    {
        "place_id": "sk_kI_VtWzZpL-rE3tx0Ezghg",
        "highlight": "<em>01004</em>, Bitarová",
        "postal_code": "01004",
        "municipality": "Bitarová",
        "object": "postal_code",
        "formatted_country": "Slovenská republika",
        "country": "SK"
    },
    {
        "place_id": "sk_JgsBii0z2iHkUTQDinNBpA",
        "highlight": "<em>01004</em>, Brezany",
        "postal_code": "01004",
        "municipality": "Brezany",
        "object": "postal_code",
        "formatted_country": "Slovenská republika",
        "country": "SK"
    },
    {
        "place_id": "sk_N1S0GEoTxnroRafQ5VF1yw",
        "highlight": "<em>01004</em>, Hôrky",
        "postal_code": "01004",
        "municipality": "Hôrky",
        "object": "postal_code",
        "formatted_country": "Slovenská republika",
        "country": "SK"
    },
    {...}
]

POST/v1/places/{place_id}

Detail miesta

Načítanie podrobností na základe identifikátora miesta. Prostredníctvom identifikátora je možné načítať adresu, ulicu, obec a poštové smerovacie čísla.

Povinné parametre

Name
place_id
Type
string
Description
Identifikátor miesta.
Name
api_key
Type
string
Description
Prístupový API kľúč môžete použiť ako parameter api_key alebo v hlavičke požiadavky X-Swiftyper-API-Key.

Výstup

Výstupom je v prípade platného id objekt s popísanými atribútmi, v opačnom prípade sa zobrazí chyba. Bežným zdrojom chýb je nezadanie API kľúču, alebo presiahnutie mesačného limitu na vyhľadávanie.

Požiadavka

curl -X POST https://api.swiftyper.sk/v1/places/sk_m16ZZTrfCm2Rfnm6oN7oeA \
   -H 'X-Swiftyper-API-Key: 2SN360bLw7lI7KB9Awu5w8oYvCWv17bsA1NAboFNo01Y'

Odpoveď

{
    "place_id": "sk_m16ZZTrfCm2Rfnm6oN7oeA",
    "highlight": "Izabely Textorisovej 4534/1, 03601 Martin, Slovenská republika",
    "formatted_address": "Izabely Textorisovej 4534/1, 03601 Martin, Slovenská republika",
    "formatted_street": "Izabely Textorisovej 4534/1",
    "street_number": "4534",
    "building_number": "1",
    "formatted_number": "4534/1",
    "municipality": "Martin",
    "postal_code": "03601",
    "region": "Žilinský kraj",
    "county": "Martin",
    "district": "Martin",
    "latlng": {
        "lat": 49.05245753,
        "lng": 18.92395417
    },
    "object": "address",
    "formatted_country": "Slovenská republika",
    "country": "SK"
}

POST/v1/places/reverse

Reverzné geokódovanie

Vyhľadávanie adresy podľa zemepisných súradníc (GPS, systém WGS84).

Povinné parametre

Name
lat
Type
string
Description
Zemepisná šírka.
Name
lng
Type
string
Description
Zemepisná dĺžka.

alebo

Name
jtskX
Type
string
Description
Súradnica JTSK osi X.
Name
jtskY
Type
string
Description
Súradnica JTSK osi Y.

Parametre

Name
distinct
Type
string
Description
Max. vzdialenosť od bodu, predvolené 10m.
Name
country
Type
string · obsahuje kód dostupnej krajiny
Description
Krajiny v ktorých sa adresa bude vyhľadávať.
Name
limit
Type
string
Description
Počet zobrazených výsledkov. Hodnota môže byť v rozmedzí 1 až 20. Predvolená hodnota je 7 výsledkov.

Výstup

Požiadavka

curl -X POST https://api.swiftyper.sk/v1/places/reverse \
   -H 'X-Swiftyper-API-Key: 2SN360bLw7lI7KB9Awu5w8oYvCWv17bsA1NAboFNo01Y' \
   -d lat=48.7444321 \
   -d lng=22.1794583

Odpoveď

[
    {
        "place_id": "sk_mhUQEtqkZZ3-SseyJ2Y2vw",
        "highlight": "Kpt.Nálepku 245/13, 07301 Sobrance, Slovenská republika",
        "formatted_address": "Kpt.Nálepku 245/13, 07301 Sobrance, Slovenská republika",
        "formatted_street": "Kpt.Nálepku 245/13",
        "street_number": "245",
        "building_number": "13",
        "formatted_number": "245/13",
        "municipality": "Sobrance",
        "postal_code": "07301",
        "street": "Kpt.Nálepku",
        "region": "Košický kraj",
        "county": "Sobrance",
        "district": "Sobrance",
        "latlng": {
            "lat": 48.74443228,
            "lon": 22.17945814
        },
        "object": "address",
        "formatted_country": "Slovenská republika",
        "country": "SK"
    }
]