API description

Introdução

A autorização das solicitações dirigidas ao Sistema de Despacho Navitel realiza-se por meio duma chave gerada nos ajustes do programa. Para gerar a chave API, vá para Ajustes > API.

Recuperar a lista de veículos

Antes de tentar de recuperar a informação sobre os veículos utilizando a chave API, é necessário obter a lista dos veículos e as suas características de identificação. Para isso, faça esta solicitação (GET):

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

o «apikey=[val]» é um parâmetro típico nome/valor. A parte «apikey» deste parâmetro é o nome e «[val]» é o lugar onde se coloca o valor. Introduza a chave API, que você receberá dos ajustes do programa, na parte do valor deste parâmetro. A solicitação correta da lista de veículos deveria ter esta forma:

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

Além disso, no final da solicitação da lista de veículos deve estar o nome do parâmetro do filtro

namefilter=[value]

o «[value]» — é o valor do filtro. Você pode colocar o nome do objeto específico do qual deseja obter informação ou pode deixar este campo em branco se deseja recuperar a lista de todos os objetos como mostra o exemplo mencionado acima.

Depois de solicitar a lista, você receberá resposta em forma de um formato de código XML.

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

A resposta contém informação sobre os veículos incluindo o grupo/a empresa, IMEI/ID do rastreador (tracker), o tipo do rastreador, ID do veículo e o nome do veículo. Você poderá usar estes dados mais tarde para identificar os veículos sobre os quais desejará obter informação.

Você pode especificar na sua solicitação o formato preferido do resultado. Para isso, adicione a extensão adequada detrás da palavra «vehicles». Possíveis extensões: «.xml» ou «.json» (esta funcionalidade está disponível para qualquer tipo de solicitação dirigida ao sistema de despacho).

Neste exemplo, o resultado será entregue em formato XML

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

e neste exemplo, o resultado será entregue em formato JSON

http://dispatch.navitel.ru/api/1.0/vehicles.json
Recuperar a informação de monitoramento

Uma solicitação regular dirigida ao sistema de despacho é basicamente uma linha que consiste num endereço básico (base-URL) e num conjunto de parâmetros da solicitação. A base-URL deve ter sempre a seguinte forma (exceto o caso quando se recupera a lista de veículos):

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

Os parâmetros da solicitação são as linhas de pares nome/valor e cada par se separa pelo sinal «&». Devem ser colocados imediatamente detrás do ponto de interrogação da base-URL. Cada parâmetro tem o seguinte formato:

field=[value]

o «[field]» é o nome do parâmetro e «[value]» é o valor do parâmetro. Como entrada se pode colocar algum destes nomes: «id», «name», «imei», «time», «what», «apikey».
A entrada é sensível a maiúsculas e minúsculas.

Uma solicitação normal conteria os seguintes parâmetros:

  1. O arquivo das identificações do veículo. Cada veículo está definido por uma de três possíveis identificações: «id», «name», «imei». A identificação é em princípio uma linha assim:

    id=[vehicle_static_id_0]

    onde «[vehicle_static_id_0]» é o ID do veículo que você pode obter solicitando a lista de veículos.

    Como as identificações são apenas meros parâmetros de nome/valor, você pode usar muitos deles para obter informação sobre vários veículos ao mesmo tempo. De maneira semelhante ao caso de outros parâmetros, as identificações devem estar separadas pelo sinal «&».

    id=[vehicle_static_id_0]&id=[vehicle_static_id_0]

    Você pode usar diferentes tipos de identificações para especificar os veículos na solicitação. Por exemplo:

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

    Não se preocupe se introduzir diferentes identificações do mesmo veículo, o veículo sempre se mostrará apenas uma vez.

  2. A chave API:

    apikey=[val]

    onde «[val]» é a chave API que você pode obter nos ajustes do sistema de despacho.

  3. O arquivo de parâmetros necessários, cada parâmetro separado pelo sinal «&»:

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

    onde «[field]» é o nome do parâmetro e «[value]» é o valor do parâmetro. Utilize as tabelas debaixo como guia para introduzir os nomes e valores de parâmetros corretos.

Parâmetros para um período fixo de tempo T

Agora, você já deveria saber introduzir os parâmetros de identificação e a API na solicitação. Mas ainda existe o parâmetro «what» que se usa para solicitar informação sobre o indicador especificado no valor do bloque do parâmetro.

Se por exemplo queremos obter informação sobre a velocidade do objeto num momento particular do tempo, usariamos o parâmetro

what=speed_kmh

e a solicitação completa teria esta forma:

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

No exemplo anterior solicitamos informação sobre a velocidade do veículo chamado «NaviCar» utilizando o código de acesso API «00000000000000000000000» para aceder ao sistema de despacho. De maneira semelhante podemos solicitar informação sobre os parâmetros enumerados na seguinte tabela. Para todos os parâmetros desta tabela se usará como nome «what» e como valor o texto da coluna «Valor» na tabela.

Descrição do parâmetro
Valor
Descrição do parâmetroignição
Valorignition
Descrição do parâmetrolatitude, longitude
Valorlat_deg, lon_deg
Descrição do parâmetrovelocidade
Valorspeed_kmh
Descrição do parâmetrodireção do movimento
Valordirection_deg
Descrição do parâmetronúmero de satélites, hdop
Valorsatellite_count, hdop
Descrição do parâmetroaltitude
Valoraltitude_m
Descrição do parâmetroparâmetros GSM (mcc, mnc, lac apod.)
Valormcc, mnc, lac, cellid, signal_strength, timing_advance
Descrição do parâmetrotensão de alimentação externa
Valorexternal_power_mv
Descrição do parâmetrotensão da bateria interna
Valorbattery_power_mv
Descrição do parâmetrotemperatura do rastreador
Valortemperature_c
Descrição do parâmetroleituras do acelerómetro (x, y, z)
Valoracceleration_x_ms2,
acceleration_y_ms2,
acceleration_z_ms2
Descrição do parâmetrobotão do alarme
Valoralarm_on
Descrição do parâmetrotemperatura do líquido de arrefecimento
Valorcoolant_temp_c
Descrição do parâmetrorotações do motor
Valorengine_rpm
Descrição do parâmetronível de combustível (%)
Valorfuel_percent
Descrição do parâmetroquilometragem
Valormileage_km
Descrição do parâmetrocombustível total consumido
Valortotal_fuel_consumed_l
Descrição do parâmetronível de combustível (CAN)
Valorcan_fuel_l
Descrição do parâmetrotempo de funcionamento do motor (CAN)
Valormhours
Descrição do parâmetrovelocidade (CAN)
Valorcan_speed_kmh
Descrição do parâmetronível de combustível (calculado, convertido etc.)
Valorfuel_l
Descrição do parâmetroentradas analógicas
Valoranalog_input
Descrição do parâmetroentradas digitais
Valordigital_input
Descrição do parâmetroentrada CAN
Valorcan_input
Descrição do parâmetrofrequência da entrada
Valorfrequency_hz
Descrição do parâmetrocontadores de impulsos
Valorpulse_counter_pcs
Descrição do parâmetrocarga por eixo
Valoraxle_load_kg
Descrição do parâmetroversão do protocolo CAN
Valorcan_log_version
Descrição do parâmetrotamanho de pacotes recebidos em bytes
Valorin_chunk_size
Descrição do parâmetronúmero de pacotes recebidos
Valorin_package_count
Descrição do parâmetrotamanho da resposta do servidor em bytes
Valorout_chunk_size
Descrição do parâmetronúmero de respostas do servidor
Valorout_package_count
Descrição do parâmetrolista de valores introduzidos por fio
Valorone_wire_input
Descrição do parâmetrolista de valores introduzidos pelos sensores
Valorsensor_input
Descrição do parâmetrolista de valores introduzidos por dispositivos analógicos
Valorvoltage_mv
Especificação do tempo

Quando na solicitação não se especifica nenhum parâmetro de tempo, a resposta inclui dados sobre o momento atual de tempo. Para especificar na solicitação um determinado momento de tempo, utilize o parâmetro especial «time»:

time=[val]

onde «[val]» é o momento de tempo especificado de acordo com a norma ISO 8601 (ver https://en.wikipedia.org/wiki/ISO_8601).
A entrada é sensível a maiúsculas e minúsculas.

Segundo esta norma, o formato de tempo é «YYYY-MM-DDThh:mm:ss». Por isso a entrada deve ter este formato:

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

se trata da data 12 de julho de 2015, às 12:00:00 horas.

Você também pode especificar uma zona horária no valor do parâmetro «time» adicionando o nome da zona horária detrás do valor (por exemplo MSK ou «Ásia/Novosibirsk».)

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

Para indicar uma zona horária UTC é suficiente colocar no final do valor do parâmetro «Z».

Você também pode ajustar o fuso horário mexendo a hora «hh:mm» para frente ou para trás até chegar à zona de tempo que precisa de ter.

time=2015-07-22T12:00:00+03:00
Especificação do intervalo de tempo

Se você deseja especificar o intervalo de tempo, indique dois momentos de tempo segundo as instruções descritas acima e separe-os com o sinal de barra.

time=[val1]/[val2]

onde «[val1]» — é o início do intervalo de tempo e «[val2]» é o seu final.

Por exemplo:

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

Neste caso o intervalo de tempo começa em 12 de julho de 2015 às 12:00:00 e termina em 15 de julho de 2015 às 15:52:01.

O intervalo de tempo se pode criar também como «o tempo de acordo com a norma ISO/duração», onde a duração do intervalo se especifica como «PxxYxxMxxDTxxHxxMxxS (onde depois do prefixo P segue a duração do intervalo respeitando maiúsculas e minúsculas). Se o intervalo de tempo está predefinido, para os parâmetros do grupo A se usará o valor mais elevado deste intervalo.

A seguinte tabela mostra a lista dos parâmetros «what» que sempre devem ser utilizados junto com os parâmetros do intervalo de tempo:

Descrição do parâmetro
Valor
Descrição do parâmetroduração do movimento
ValormoveTime
Descrição do parâmetroduração da parada
ValorstopTime
Descrição do parâmetroparada sem dados
ValorlostSignalTime
Descrição do parâmetroquilometragem percorrida
ValorkilometresTravelled
Descrição do parâmetroconsumo de combustível em litros
ValortotalFuelConsumption
Descrição do parâmetrovelocidade média
ValoravgMoveSpeed
Descrição do parâmetrovelocidade máxima
ValormaxSpeed
Descrição do parâmetroponto inicial
Valororigin
Descrição do parâmetroponto de destino
Valordestination
Descrição do parâmetronível de combustível no início/no final
ValorendFuelLevel, startFuelLevel
Descrição do parâmetroconsumo de combustível (em litros) por 100 km
ValorfuelPer100Km
Descrição do parâmetrocontagem de combustível/drenagem (número de eventos)
ValorfuelingCount, fuelDrainCount
Descrição do parâmetrocontagem de combustível/drenagem (em litros)
ValortotalFueling, totalFuelDrain