====== InternetLocAPI ======

<WRAP center round info 60%>
https://internetlocapi.faster.cz/
</WRAP>


Soukromé API které slouží k zjištění připojitelnosti budovy přes Optické trasy Faster CZ.

  * Komunikace probíhá přes HTTPS
  * Klient posílá POST s JSON payloadem a obdrží výsledek jako JSON
  * Jedná se o soukromé API - je třeba mít API klíč

==== Endpointy ====

^ Adresa      ^ Použití       ^ 
|/address/free|Vyhledávání připojitelnosti podle libovolné adresy|
|/address/exact|Vyhledávání připojitelnosti podle přesně definované adresy|
|/gcs|Vyhledávání připojitelnosti podle souřadnic LAT a LON|
|/ruian|Vyhledávání připojitelnosti podle ID v RÚIAN|

==== Popis ====

=== Výsledek ===

Výsledek jsou dvě hodnoty: pripojitelnost a vzdalenost.

pripojitelnost říká jestli a případně jak je možné hledanou lokalitu připojit.
Možné hodnoty jsou:
  - Nedostupné (nelze připojit)
  - Dostupné (pravděpodobně samotný přípojný bod)
  - Dostupné - optický spoj v objektu (neměl by být problém připojit optikou)
  - Dostupné - optický spoj v dosahu (mělo by být možné připojit optikou)
  - Dostupné - radiový spoj v objektu (nelze připojit přes optiku ale bezdrátové připojení by neměl být problém)
  - Dostupné - radiový spoj v dosahu (mělo by být možné připojit přes bezdrátové připojení)

<WRAP center round important 90%>
Hodnoty jsou orientační, pokud API vrátí například hodnotu 4 neznamená to že na 100% je možné objekt připojit ale znamená to že je reálné připojit objekt optikou od Faster CZ a na 100% to potvrdí až náš technik po obhlídce.
</WRAP>

vzdalenost slouží k debugování a říká vzdálenost hledané oblasti od nejbližšího přípojného bodu.

Příklad odpovědi:
<code javascript>
{
   "pripojitelnost": 2,
   "vzdalenost": 0.095
}
</code>

=== /address/free ===

Slouží k jednoduchému hledání, do hodnoty "name" můžete vložit libovolné údaje a na základě nich dostanete výsledek.

Informace z tohoto endpointu mohou být nepřesné (například pokud dvě obce mají stejný název ulice a uživatel nespecifikuje město)

Příklad JSON:
<code javascript>
{
   "name":"Jarní 1064/44g",
   "apikey":"yourapikey"
}
</code>

=== /address/exact ===

Slouží k hledání pokud máte všechny dané informace.

Informace z tohoto endpointu jsou přesné pokud vyplníte dané informace správně.

Příklad JSON:
<code javascript>
{
   "street":"Jarní",
   "city":"Brno",
   "housenumber":"1064/44",
   "county":"Jihomoravský kraj",
   "country":"CZ",
   "apikey":"yourapikey"
}
</code>

=== /gcs ===

Slouží k hledání pokud máte adresu v zeměpisných souřadnicích (geographic coordinate system (GCS)).

Informace z tohoto endpointu jsou přesné a pokud máte adresu v tomto formátu je to preferovaný způsob pro dotazy.

Příklad JSON:
<code javascript>
{
   "lat":49.1979883,
   "lon":16.6145102,
   "apikey":"yourapikey"
}
</code>

=== /ruian ===

Slouží k hledání podle ID v Registru územní identifikace, adres a nemovitostí (RÚIAN).

Informace z tohoto endpointu jsou přesné a pokud máte adresu v tomto formátu.

Příklad JSON:
<code javascript>
{
   "id":42667887,
   "apikey":"yourapikey"
}
</code>

==== Příklad dotazu přes curl ====

<code bash>
curl -X POST -H "Content-Type: application/json" -d '{"lat":49.1979883,"lon":16.6145102,"apikey":"yourapikey"}' 'https://internetlocapi.faster.cz/gcs'
</code>

==== Chybové hlášky ====

Chyby vrací pod různými kódy hodnota "chyba" v odpovědi.

Příklad chyby:
<code javascript>
{
   "chyba":1
}
</code>


  - Špatný API klíč
  - Nenalezený objekt