Dokumentace API

Úvod

Autorizace požadavků na systém Navitel Dispatch je provedena s využitím API klíče vygenerovaného v nastavení programu. Pro vygenerování přejděte do Nastavení > API.

Získání seznamu vozidel

Nežli se pokusíme získat informace o vozidlech pomocí klíče API, je nejprve nutné získat seznam vozidel s jejich identifikačními znaky. K tomu využijeme následující požadavek:

http://dispatch.navitel.ru/api/1.0/vehicles.xml?apikey=[val]&namefilter=

kde „apikey=[val]” je typicky název/hodnota parametru. Část „apikey” tohoto parametru je název, zatímco část „[val]” je určena pro vstupní hodnoty. Vložte klíč API, který jste získali v nastavení programu, jako hodnotu tohoto parametru. Vlastní požadavek na seznam vozidel by měl vypadat obdobně jako zde:

http://dispatch.navitel.ru/api/1.0/vehicles.xml?apikey=00000000000000000000000&namefilter=

Kromě toho se na konci požadavku musí vyskytovat parametr „namefilter”

namefilter=[value]

kde „[value]” je hodnota filtru. Můžete uvést konkrétní název objektu, o kterém chcete získat informace nebo můžete nechat pole prázdné, chcete-li získat seznam všech objektů, jak bylo uvedeno v příkladu výše.

Po zadání požadavku na seznam vozidel obdržíte odpověď ve formě XML kódu.

<reply> <result type="array"> <v i="0"> <group_name>security_group</group_name> <tracker_id>GALILEOSKY:00000000000000000000000000000000</tracker_id> <tracker_type>GALILEOSKY</tracker_type> <vehicle_id>xxxxx-xxxx-xxxx-xxxxxxxxxxxx</vehicle_id> <vehicle_name>Subaru</vehicle_name> </v> <v i="1"> <group_name>security_group</group_name> <tracker_id>GRANIT:00000000000000000000000000000</tracker_id> <tracker_type>GRANIT04</tracker_type> <vehicle_id>xxxxx-xxxx-xxxx-xxxxxxxxxxxx</vehicle_id> <vehicle_name>cardabalet</vehicle_name> </v> </result> </reply>

Odpověď obsahuje informace o vozidlech, zahrnující skupinu/společnost, IMEI/ID stopy, typ stopy, ID vozidla a jméno vozidla. Poté již budete moci využít data s cílem identifikovat vozdila, o kterých chcete získat informaci.

Můžete také zadat preferovaný formát výsledku ve vašem požadavku. Za slovo „vehicles” přidejte vhodnou příponu. Možné přípony: „.xml” nebo „.json” (tato funkce je k dispozici pro všechny typy požadavků v systému Navitel Dispatch).

Výsledky v následujícím případě budou získány ve formátu XML

http://dispatch.navitel.ru/api/1.0/vehicles.xml

v tomto případě budo výsledky ve formě kódu JSON

http://dispatch.navitel.ru/api/1.0/vehicles.json
Získání informací o monitorování

Obvyklý požadavek na dispatch systém je v podstatě řádek skládající se ze základní URL adresy a sady parametrů. Základní URL adresa by měla být vždy následující (s vyjímkou při získávání seznamu vozidel):

http://dispatch.navitel.ru/api/1.0/vehicleinfo.xml?

Parametry požadavku jsou vždy ve tvaru název/hodnota a jednotlivé parametry jsou od sebe odděleny symbolem „&”. Všechny takové parametry by měly být umístěné v adrese URL vpravo od znaku otazníku. Každý parametr má nasledující formu:

field=[value]

kde „[field]” je název parametru a „[value]” je hodnota parametru. Existuje hned několik názvů parametru: „id”, „name”, „imei”, „time”, „what”, „apikey”. Vstup rozlišuje malá a velká písmena.

Požadavek by měl za normálních okolností obsahovat parametry uvedené níže:

  1. Sada pro identifikaci vozidel. Každé vozidlo je identifikováno pomocí jednoho ze tří možných identifikátorů: „id”, „name”, „imei”. Identifikace je v podstatě tohoto typu:

    id=[vehicle_static_id_0]

    kde „[vehicle_static_id_0]” je ID vozidla, které můžete získat z požadavku na seznam vozidel.

    Vzhledem k tomu, že identifikace spočívá pouze v názvu parametru a jeho hodnotě, můžete využít více parametrů pro získání informace o více vozidlech najednou. Podobně jako u jiných parametrů, identifikace by měly být odděleny symbolem „&”.

    id=[vehicle_static_id_0]&id=[vehicle_static_id_0]

    Využít můžete také různé druhy identifikace pro specifikaci vozidla. Například:

    id=[vehicle_static_id_0]&name=[vehicle_name]&imei=[vehilce_imei]&id=[vehicle_static_id_N]

    Pokud se Vám náhodou stane, že zadáte rozdílnou identifikaci pro stejné vozidlo, nebojte se, vozidlo bude vždy zobrazeno pouze jednou.

  2. API klíč:

    apikey=[val]

    kde „[val]” je klíč API, který lze získat v nastavení dispatch systému.

  3. Sada potřebných parametrů, každý parametr je oddělen symbolem „&”:

    field=[value]&field=[value]&field=[value]

    kde „[field]” je název parametru a „[value]” je hodnota parametru. Pro správné zadání názvů a hodnot parametrů využijte tabulky uvedené níže.

Parametry stanovené doby T

Nyní jste již seznámeni s tím, jak zahrnout identifikační a API parametry do Vašeho požadavku. Ale existuje také parametr „what”, který se používá k získávání informace o indikátorech uvedených v hodnotě bloku parametrů.

Řekněme, pokud bychom chtěli získat informaci o rychlosti objektu v daném okamžiku, využili bychom parametr:

what=speed_kmh

poté by celý požadavek vypadal takto:

http://dispatch.navitel.ru/api/1.0/vehicleinfo.xml?apikey=00000000000000000000000&name=NaviCar&what=speed_kmh

Ve výše uvedeném příkladu jsme získali informaci o rychlosti vozidla s názvem „NaviCar” využívající API přístupový kód „00000000000000000000000” k přístupu do dispatch systému. Stejně tak můžeme získat informace o parametrech uvedených v následující tabulce. Název pro všechny parametry této tabulky je „what”; hodnota parametru by měla být převzata z tabulky ze sloupce „Hodnota”.

Popis parametrů
Hodnota
Popis parametrůzapalování
Hodnotaignition
Popis parametrůzeměpisná šířka, zeměpisná délka
Hodnotalat_deg, lon_deg
Popis parametrůrychlost
Hodnotaspeed_kmh
Popis parametrůsměr pohybu
Hodnotadirection_deg
Popis parametrůpočet satelitů, hdop
Hodnotasatellite_count, hdop
Popis parametrůvýška
Hodnotaaltitude_m
Popis parametrůparametry gsm (mcc,mnc,lac atd.)
Hodnotamcc, mnc, lac, cellid, signal_strength, timing_advance
Popis parametrůvnější náhradní elektrické napětí
Hodnotaexternal_power_mv
Popis parametrůvnitřní elektrické napětí baterie
Hodnotabattery_power_mv
Popis parametrůteplota zařízení
Hodnotatemperature_c
Popis parametrůměření zrychlení (x, y, z)
Hodnotaacceleration_x_ms2,
acceleration_y_ms2,
acceleration_z_ms2
Popis parametrůtlačítko alarm
Hodnotaalarm_on
Popis parametrůteplota chladící kapaliny
Hodnotacoolant_temp_c
Popis parametrůrychlost otáček
Hodnotaengine_rpm
Popis parametrůhladina paliva (%)
Hodnotafuel_percent
Popis parametrůpočet najetých kilometrů
Hodnotamileage_km
Popis parametrůcelková spotřeba paliva
Hodnotatotal_fuel_consumed_l
Popis parametrůhladina paliva (CAN)
Hodnotacan_fuel_l
Popis parametrůdoba provozu motoru (CAN )
Hodnotamhours
Popis parametrůrychlost (CAN)
Hodnotacan_speed_kmh
Popis parametrůhladina paliva (vypočítaná, přepočítaná atd.)
Hodnotafuel_l
Popis parametrůanalogové vstupy
Hodnotaanalog_input
Popis parametrůdigitální vstupy
Hodnotadigital_input
Popis parametrůvstup CAN
Hodnotacan_input
Popis parametrůfrekvenční vstup
Hodnotafrequency_hz
Popis parametrůpočítadlo impulzů
Hodnotapulse_counter_pcs
Popis parametrůzatížení nápravy
Hodnotaaxle_load_kg
Popis parametrůverze logu CAN
Hodnotacan_log_version
Popis parametrůvelikost příjmaného souboru v bytech
Hodnotain_chunk_size
Popis parametrůpočet přijatých souborů
Hodnotain_package_count
Popis parametrůvelikost serverových odpovědí v bytech
Hodnotaout_chunk_size
Popis parametrůpočet serverových odpovědí
Hodnotaout_package_count
Popis parametrůseznam vstupních hodnot
Hodnotaone_wire_input
Popis parametrůseznam vstupních hodnot senzorů
Hodnotasensor_input
Popis parametrůseznam analogových vstupních hodnot
Hodnotavoltage_mv
Specifikace času

Pokud není v požadavku časový parametr specifikován, výsledek obsahuje údaje o současném časovém okamžiku. Pro specifikaci odlišného okamžiku v čase se využívá speciální časový parametr:

time=[val]

kde „[val]” je okamžik v čase určený v souladu s normou ISO 8601 (viz https://en.wikipedia.org/wiki/ISO_8601).
Vstup rozlišuje malá a velká písmena.

Podle této normy je čas uváděn ve formátu „YYYY-MM-DDThh:mm:ss”. Z tohoto důvodu bude vstup vypadat takto:

time=2015-07-12T12:00:00

kde datum je 12. července 2015 a čas 12:00:00.

V hodnotě parametru je také možné zadat časové pásmo a to přidáním názvu časového pásma na konec hodnoty parametru (například: CET nebo „Europe/Prague”).

time=2015-07-12T12:00:00CEST

Pro zadání časového pásma UTC stačí přidat „Z” na konec hodnoty parametru.

Časové pásmo můžete nastavit také pouhým pohybem času „hh:mm” dopředu či dozadu až dokud nedosáhnete potřebného časového pásma.

time=2015-07-22T12:00:00+03:00
Specifikace časového intervalu

Chcete-li specifikovat časový interval, který je ohraničen dvěma časovými okamžiky, budete postupovat stejně jako v předchozí kapitole s rozdílem, že dva časové okamžiky oddělíte od sebe lomítkem.

time=[val1]/[val2]

kde"[val1]" je začátek časového intervalu, zatímco „[val2]” je jeho konec.

Příklad:

time=2015-07-12T12:00:00/2015-07-15T15:52:01

To znamená, že časový interval začíná 12. července 2015 ve 12:00:00 a končí 15. července 2015 v 15:52:01.

Je také možné vytvořit časový interval ve formě „IsoTime/duration”, kde „duration” je doba trvání intervalu a je definována jako „PxxYxxMxxDTxxHxxMxxS” (po předponě P následuje doba trvání, malými písmeny). Pokud máme sadu časových intervalů, největší hodnota z intervalu je považována za parametr skupiny A.

Níže uvedená tabulka zachycuje seznam parametrů „what”, které by měly být používány vždy společně s časovými parametry:

Popis parametrů
Hodnota
Popis parametrůdoba pohybu
HodnotamoveTime
Popis parametrůdoba stání
HodnotastopTime
Popis parametrůdoba stání bez dat (ztráta signálu)
HodnotalostSignalTime
Popis parametrůpočet najetých kilometrů
HodnotakilometresTravelled
Popis parametrůcelková spotřeba paliva (v litrech)
HodnotatotalFuelConsumption
Popis parametrůprůměrná rychlost
HodnotaavgMoveSpeed
Popis parametrůnejvyšší rychlost
HodnotamaxSpeed
Popis parametrůvýchozí bod
Hodnotaorigin
Popis parametrůcílový bod
Hodnotadestination
Popis parametrůkonečný/počáteční stav hladiny paliva
HodnotaendFuelLevel, startFuelLevel
Popis parametrůspotřeba paliva (v litrech /100km)
HodnotafuelPer100Km
Popis parametrůpočet tankování (události)
HodnotafuelingCount, fuelDrainCount
Popis parametrůcelkový počet natankovaného paliva (litry)
HodnotatotalFueling, totalFuelDrain