Descriere API

Introducere

Autorizarea cererilor transmise către Sistemul de Expediere Navitel se efectuează folosind o cheie API generată în setările programului. Pentru a genera o cheie API, mergeți la Setări > API.

Obținerea listei de vehicule

BÎnainte de a încerca să obțineți informații despre vehicule cu ajutorul unei chei API, trebuie să obțienți lista de vehicule și caracteristicile de identificare ale acestora. Pentru aceasta, trimiteți o solicitare (OBȚINE):

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

unde „apikey=[val]” este un parametru obișnuit nume/valoare. Partea „apikey” a acestui parametru este numele, în timp ce „[val]” este un loc pentru introducerea valorii. Introduceți cheia API pe care o primiți din setările programului în partea corespunzătoare valorii a acestui parametru. Prin urmare, o solicitare corespunzătoare pentru obținerea listei de vehicule ar fi similară cu aceasta:

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

În plus, parametrul nume filtru trebuie să se afle la finalul solicitării de obținere a listei de vehicule

namefilter=[value]

unde „[value]” – este valoarea filtrului. Puteți indica un anumit nume de obiect despre care doriți să obțineți informații sau puteți lăsa câmpul necompletat, dacă doriți să obțineți lista cu toate obiectele, așa cum se arată în exemplul de mai sus.

După solicitarea listei de vehicule, primiți un răspuns sub forma unei bucăți de cod XML sau JSON.

<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>

Răspunsul include informații despre vehicule, inclusiv grupul/compania, imei/id-ul sistemului de urmărire, tipul sistemului de urmărire, id-ul vehiculului și numele vehiculului. Veți putea folosi aceste date ulterior, pentru a identifica vehiculele în legătură cu care doriți să obțineți informații.

Puteți specifica formatul preferat al rezultatului în solicitarea dvs. Pentru aceasta, adăugați extensia corespunzătoare după cuvântul „vehicule”. Extensii posibile: „.xml” sau „.json” (această funcție este disponibilă pentru orice tip de solicitare către sistemul de expediere).

Rezultatul din acest exemplu va fi livrat în format XML

https://www.dispatch.navitel.ru/api/1.0/vehicles.xml

iar în acest exemplu, rezultatul va fi livrat sub formă de cod JSON

https://www.dispatch.navitel.ru/api/1.0/vehicles.json
Obținerea informațiilor de monitorizare

O solicitare obișnuită către sistemul de expediere este, în esență, un rând care constă într-un URL de bază și un set de parametri de solicitare. URL-ul de bază ar trebui să arate întotdeauna astfel (exceptând cazul în care se obține lista de vehicule):

https://www.dispatch.navitel.ru/api/1.0/vehicleinfo.xml?

Parametrii solicitării sunt un rând cu numele/perechile de valori, fiecare pereche fiind separată printr-un ampersand („&”). Se vor amplasa chiar sub semnul întrebării al URL-ului de bază. Fiecare parametru are următorul format de nume/valoare:

field=[value]

unde „[field]” este numele parametrului, iar „[value]” este valoarea parametrului. Există mai multe nume disponibile pentru a fi introduse: „id”, „name”, „imei”, „time”, „what”, „apikey”. Datele introduse sunt sensibile la litere mari și mici.

În mod normal, o solicitare trebuie să conțină parametrii indicați mai jos:

  1. 1. Un set de date de identificare ale vehiculelor. Orice vehicul este identificat prin unul din trei elemente de identificare posibile: „id”, „name”, „imei”. În esență, elementul de identificare este un rând de tipul:

    id=[vehicle_static_id_0]

    unde „[vehicle_static_id_0]” este ID-ul vehiculului pe care îl obțineți solicitând lista de vehicule.

    Având în vedere că elementele de identificare sunt simpli parametri de nume/valoare, multe dintre acestea pot fi folosite pentru a primi informații despre mai multe vehicule simultan. Similar altor parametrii, elementele de identificare trebuie separate printr-un ampersand.

    id=[vehicle_static_id_0]&id=[vehicle_static_id_0]

    Puteți folosi diferite tipuri de elemente de identificare atunci când specificați vehicule în solicitarea dvs. De exemplu:

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

    Dacă se întâmplă să introduceți elemente de identificare diferite ale aceluiași vehicul, nu vă faceți griji, vehiculul va fi afișat întotdeauna o singură dată.

  2. O cheie API:

    apikey=[val]

    unde „[val]” este cheia API pe care o primiți în setările sistemului de expediere.

  3. 3. Setul de parametri necesari, fiecare parametru trebuie separat printr-un ampersand („&”):

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

    unde „[field]” este numele parametrului, iar „[value]” este valoarea parametrului. Folosiți tabelul de mai jos pentru numele și valorile corecte ale parametrilor.

Parametri pentru o perioadă de timp fixă T

Până în momentul de față, ar trebui să știți deja cum să includeți elementul de identificare al vehiculului și cheia API în solicitare. Dar mai există și parametrul „what” care este folosit pentru a solicita informații despre un indicator specificat în valoarea blocului de parametri.

Să spunem că, că dacă aș dori să primesc informații despre viteza unui obiect în acest moment, aș folosi parametrul

what=speed_kmh

atunci, solicitarea completă ar fi următoarea:

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

În exemplul de mai sus, au fost solicitate informații despre viteza vehiculului și a fost folosită o cheie API de acces pentru accesarea sistemului de expediere. Vehiculul a fost identificat acolo ca „NaviCar”, iar cheia API a fost identificată ca „00000000000000000000000”. În mod similar, puteți solicita informații despre parametrii incluși în tabelul de mai jos. Numele tuturor parametrilor din acest tabel este „what”; valoarea trebuie luată din coloana „value” a tabelului.

Descriere parametru
Valoare
Descriere parametrucontact
Valoarecontact
Descriere parametrulatitudine, longitudine
Valoarelat_deg, lon_deg
Descriere parametruviteză
Valoarespeed_kmh
Descriere parametrudirecție de deplasare
Valoaredirection_deg
Descriere parametrunumăr de sateliți, hdop
Valoaresatellite_count, hdop
Descriere parametruînălțime
Valoarealtitude_m
Descriere parametruparametri gsm (mcc, mnc, lac etc)
Valoaremcc, mnc, lac, cellid, signal_strength, timing_advance
Descriere parametrutensiune de alimentare externă
Valoareexternal_power_mv
Descriere parametrutensiune de alimentare internă
Valoarebattery_power_mv
Descriere parametrutemperatura sistemului de urmărire
Valoaretemperature_c
Descriere parametrucitiri accelerometru (x, y, z)
Valoareacceleration_x_ms2,
acceleration_y_ms2,
acceleration_z_ms2
Descriere parametrubuton de alarmă
Valoarealarm_on
Descriere parametrutemperatura lichidului de răcire
Valoarecoolant_temp_c
Descriere parametrurata de rotație a motorului
Valoareengine_rpm
Descriere parametrunivel combustibil (%)
Valoarefuel_percent
Descriere parametrunivel combustibil (%)
Valoaremileage_km
Descriere parametrutotal combustibil consumat
Valoaretotal_fuel_consumed_l
Descriere parametrunivel combustibil (rezervor)
Valoarecan_fuel_l
Descriere parametrutimp de funcționare motor (rezervor)
Valoaremhours
Descriere parametruviteză (rezervor)
Valoarecan_speed_kmh
Descriere parametrunivel combustibil (calculat, convertit etc.)
Valoarefuel_l
Descriere parametruintrări analogice
Valoareanalog_input
Descriere parametruintrări digitale
Valoaredigital_input
Descriere parametruintrare rezervor
Valoarecan_input
Descriere parametruintrare frecvență
Valoarefrequency_hz
Descriere parametrucontoare impuls
Valoarepulse_counter_pcs
Descriere parametrusarcină pe osie
Valoareaxle_load_kg
Descriere parametruversiune jurnal rezervor
Valoarecan_log_version
Descriere parametrudimensiunea pachetelor primite în octeți
Valoarein_chunk_size
Descriere parametrunumărul de pachete primite
Valoarein_package_count
Descriere parametrudimensiunea răspunsului serverului în octeți
Valoareout_chunk_size
Descriere parametrunumărul de răspunsuri ale serverului
Valoareout_package_count
Descriere parametrulista de valori introduse pentru cabluri
Valoareone_wire_input
Descriere parametrulista de valori introduse pentru senzor
Valoaresensor_input
Descriere parametrulista de valori analogice introduse
Valoarevoltage_mv
Specificarea orei

Atunci când nu se specifică niciun parametru timp în solicitare, răspunsul include date despre momentul prezent. Pentru specificarea unui anumit moment în solicitare, se folosește un parametru timp special:

time=[val]

unde „[val]” este un moment specificat în conformitate cu standardul ISO 8601 (consultați https://en.wikipedia.org/wiki/ISO_8601).
Datele introduse sunt sensibile la litere mari și mici.

Conform acestui standard, formatul timpului este „AAAA-LL-ZZOhh:mm:ss”. Prin urmare, valorile introduse trebuie să arate astfel:

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

unde data este indicată ca 12 iulie 2015, iar ora este 12:00:00.

De asemenea, puteți specifica un fus orar în valoarea parametrului timp, adăugând fusul orar la finalul valorii (de exemplu, MSK sau „Asia/Novosibirsk”).

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

Pentru a indica fusul orar UTC, adăugați pur și simplu „Z” la finalul valorii parametrului.

În plus, fusul orar poate fi stabilit indicând direct ora față de UTC.

time=2015-07-22T12:00:00+03:00
Specificarea intervalului de timp

Dacă doriți să specificați un interval de timp, indicați 2 momente, așa cum se arată în capitolul anterior și separați-le cu ajutorul simbolului bară oblică.

time=[val1]/[val2]

unde „[val1]” – este începutul intervalului de timp, în timp ce „[val2]” este sfârșitul acestuia.

De exemplu:

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

Aceasta înseamnă că intervalul de timp începe în data de 12 iulie 2015 la ora 12:00:00 și se încheie în data de 15 iulie 2015 la ora 15:52:01.

De asemenea, poate fi creat un interval de timp în format „IsoTimp/durată”, unde durata intervalului este specificată ca „PxxYxxMxxDTxxHxxMxxS (prefixul P este urmat de durata intervalului, sensibil la litere mari și mici). În cazul în care există un interval de timp stabilit, cea mai mare valoare din acest interval este luată pentru parametrii din grupul A.

Tabelul de mai jos furnizează lista parametrilor „what” care trebuie să fie folosiți întotdeauna împreună cu parametrii intervalului de timp:

Descriere parametru
Valoare
Descriere parametrudurata deplasării
ValoaremoveTime
Descriere parametrudurata staționării
ValoarestopTime
Descriere parametrustaționare fără date
ValoarelostSignalTime
Descriere parametrukilometraj
ValoarekilometresTravelled
Descriere parametruconsum de combustibil în litri
ValoaretotalFuelConsumption
Descriere parametruviteză medie
ValoareavgMoveSpeed
Descriere parametruviteză maximă
ValoaremaxSpeed
Descriere parametrupunct inițial
Valoareorigin
Descriere parametrupunct de destinație
Valoaredestination
Descriere parametrunivelul combustibilului la final/început
ValoareendFuelLevel, startFuelLevel
Descriere parametruconsum de combustibil (litri) la /100 km
ValoarefuelPer100Km
Descriere parametrucontor golire rezervor (evenimente)
ValoarefuelingCount, fuelDrainCount
Descriere parametrucontor golire rezervor (litri)
ValoaretotalFueling, totalFuelDrain