Muitas frustrações com o aplicativo oficial SIU Mobile me motivaram a escrever essa documentação. Toda a API foi especificada com o máximo de informações encontradas.
Este documento é totalmente privado e foi disponibilizado em link de Gist secreto para uso interno nas empresas que representam o SIU Mobile BH.
Todo o conteúdo foi observado através da transmissão de dados pela rede. Não foi utilizado nenhum código da aplicação.
Conheça o Autor no fim do documento.
A API apresenta estrutura simples, mas mal elaborada. Possui falhas graves de segurança, tecnologia obsoleta e troca de dados sem criptografia. É estável e tem baixa latência.
Todas as requisições são realizadas via HTTP e sem criptografia.
A API apresenta o padrão REST, mas o único método disponível é GET, não foi encontrado o uso de POST ou outro metódo de requisição.
Nota-se após alguns testes, que a API retorna respostas vazias em caso de muitas requisições em um curto período. Não se sabe este limite até o momento.
A API não faz utilização de token ou nenhuma outra identificação nas requisições, apenas um callback com dados de jQuery, no qual não foi identificado seu uso (talvez seja para uso do aplicativo).
Todo o conteúdo é obtido dentro de retorno*JSON*( -- JSON -- ), sendo * uma possibilidade de texto adicional, mas opcional. Sendo assim é necessário sua remoção para não quebrar os métodos de parse padrões das linguagens. Eu não sabia quando escrevi isso, mas o nome dado a essa técnica é JSONP.
O endereço padrão da API é http://mobile-l.sitbus.com.br:6060/siumobile-ws-v01/rest/ws/ e após alguns recursos e seus parâmetros, é necessário especificar retornoJSON ao fim do endereço (Não se sabe se há versão XML).
Alguns recursos tem um parâmetro que sempre é 0. Motivo desconhecido.
-
Evite praticas abusivas que possam causar bloqueios pela empresa que fornece os dados.
-
Algumas palavras capitalizadas, seja no plural ou singular, indicam Objetos especificados neste documento.
-
Não foi considerado o cálculo de rotas, acessibilidade e relacionados.
A Linha dentro da API pode ser identificada nas respostas como cod e cod_linha, e dentro do documento como cod ou codLinha e é do tipo Int.
A identificação humana e da BHTrans é conhecida como sgl, sgLin ou num_linha e é do tipo String.
Uma sublinha é identificada como cod apenas dentro do recurso de solicitação de SubLinhas e é do tipo Int, mas não foi encontrada sua utilização em outros recursos. Notas abaixo.
A Parada dentro da API pode ser identificada nas respostas como cod e no documento como codParada e cod, sendo do tipo String
A identificação humana e da BHTrans é conhecida como siu e é do tipo String.
As previsões podem ser retornadas de duas formas, sendo uma o horário de sáida do próximo ônibus, apenas caso não tenha nenhum em rota, e o tempo estimado de chegada.
Exemplos: "prev": "6 Minutos" ou "prev": "SAÍDA: 19:00"
As cores são representadas por Int e a classificação não foi verificada. Veja a tabela:
| cor(Int) | Cor |
|---|---|
1 |
Branco/Cinza Claro |
2 |
Cinza Escuro/Preto |
3 |
Cinza |
4 |
Azul (Claro) |
5 |
Azul |
6 |
Roxo |
7 |
Rosa |
8 |
Amarelo |
9 |
Amarelo Âmbar/Laranja |
10 |
Vermelho |
11 |
Verde/Move |
12 |
Verde |
13 |
Laranja |
Essa variável mostra se o ônibus possui elevadores, notou-se que se o valor for > 0, o ônibus é acessível. Quando é um ônibus que não está a caminho, o valor retornado costuma ser 0.
O aplicativo faz uso desse recurso apenas durante a solicitação do quadro de horários. O usuário seleciona a Linha, ele pede a subLinha e depois pede o quadro de horários a partir da subLinha. Neste caso, os dados do quadro de horários obtidos utilizando esses parâmetros são idênticos.
Em outros testes notou-se que os dados recebidos em outros recursos possuem algumas diferenças ao utilizar os parâmetros codLinha ou codSubLinha, porém nenhuma conclusão foi obtida a partir destas diferenças.
Por exemplo, foi notado ao solicitar o Itinerário usando codLinha que alguns endereços retornados não fazem parte da rota padrão do ônibus, enquanto os endereços retornados em codSubLinha faziam parte da rota padrão do ônibus. O Itinerário recebido em codLinha aparentou receber endereços utilizados em eventos ou desvios de rotas. O aplicativo oficial sempre solicita o Itinerário a partir do codLinha.
É possível que você receba o Array previsoes vazio [] caso não haja nenhum ônibus a caminho, se o ônibus estiver a mais de 30 minutos de distância ou se não houver nenhuma saída programada para os próximos 30 minutos.
Notou-se que em algumas respostas, o identificador da BHTrans, que é o código conhecido no mapeamento da cidade e que normalmente está exibido na própria parada, pode ser recebido vazio. Não foi compreendido o motivo.
No recurso de previsão de uma parada é possível perceber que há o valor apelidoLinha e esse valor define apenas os pontos de parada final e inicial do ônibus, mas sem uma ordem específica. Este valor também foi encontrado como descricao no recurso de Linhas de um Parada.
Exemplo: "apelidoLinha": "EST.PAMPULHA/CENTRO/HOSPITAIS"
Este nome não significa que o ônibus está fazendo o trajeto na respectiva ordem, então ele possivelmente está seguindo a rota Hospitais -> Centro -> Estação Pamupulha ou Estação Pampulha -> Centro -> Hospitais.
O rastreamento de veículos funciona a noite, porém o aplicativo oficial não exibe o mapa quando solicitado pelo usuário e acusa uma falha de JavaScript.
Em atualização recente, o mapa foi corrigido e funciona a noite.
É possível receber uma lista de todas as Linhas disponíveis através do recurso buscarLinhas. A requisição é direta e não necessita de parâmetros.
http://mobile-l.sitbus.com.br:6060/siumobile-ws-v01/rest/ws/buscarLinhas/retornoJSONListaLinhas
A resposta será
- sucesso - Bool
- linhas - String JSON de Linhas
- sublinhas - NULL Sempre vazio
Na resposta recebemos uma String linhas com o conteúdo de outro JSON e todas as Linhas dentro. Você vai precisar de um parse dessa String, e o conteúdo está declado dentro de aspa simples.
e cada Linha é especificada como
- cod - String Identificação da Linha na API
- sgl - String Identificação da Linha na BHTrans
- nom - String Nome da Linha/Destinos
{
"sucesso": true,
"linhas": "[{'cod':'5','sgl':'101','nom':'AGLOMERADO SANTA LUCIA'},{'cod':'7','sgl':'102','nom':'NOSSA SENHORA DE FATIMA/HOSPITAL EVANGELICO'}]"
}A solicitação de dados de uma Linha é realizada com o parâmetro codLinha (e do 0) recebido na requisição da listagem de Linhas e no recurso buscarParadasPorLinha. Fique atento às informações abaixo.
http://mobile-l.sitbus.com.br:6060/siumobile-ws-v01/rest/ws/buscarParadasPorLinha/$codLinha/0/retornoJSON
A resposta será
- sucesso - Bool
- paradas - Array de Paradas
e cada Parada é especificada como
- cod - Int Código da Parada na API
- end - String Endereço
- siu - String Código na BHTrans
- sent - String Origem [Identificador Primário]
- temVeic - Bool Desconhecido
É importante perceber que a Origem, declarada como sent, é um identificador da origem do ônibus, então você vai precisar separar as paradas a partir desse identificador. Por exemplo, podemos receber um Array com 50 paradas, sendo 25 com Origem x e outros 25 como Origem y, logo temos dois identificadores de Origem. É simplesmente a rota que o ônibus toma a partir do seu ponto de partida.
Não foi feita a análise do temVeic, mas há a possibilidade de verificar se há um veículo naquela parada no momento da solicitação.
{
"sucesso": true,
"paradas": [
{
"cod": 4113,
"end": "RUA CORONEL FIGUEIREDO, 359",
"siu": "10370",
"sent": "SANTA CRUZ",
"temVeic": false
},
{
"cod": 4113,
"end": "RUA CORONEL FIGUEIREDO, 359",
"siu": "10370",
"sent": "SAUDADE",
"temVeic": false
}
]
}As paradas próximas podem ser obtidas com dados de localização, sendo latitude, longitude (e do 0), respectivamente, no recurso buscarParadasProximas.
http://mobile-l.sitbus.com.br:6060/siumobile-ws-v01/rest/ws/buscarParadasProximas/$longitude/$latitude/0/retornoJSON
A resposta será
- sucesso - Bool
- paradas - Array de Parada
e cada Parada (nesse contexto) é especificada como
- cod - Int Identificação da Parada na API
- siu - String Identificação da Parada na BHTrans
- x - Double Longitude
- y - Double Latitude
- desc - String Nome da Parada
Note que a Parada não é a mesma da requisição a partir de uma Linha específica.
{
"sucesso":true,
"paradas":[
{"cod":5714,
"siu":"90097",
"x":-43.939132,
"y":-19.919519,
"desc":"AVE AMAZONAS, 471"
}
]
} As intruções são semelhantes às da requisição anterior, porém o recurso solicitado é buscarDadosParada e o parâmetro é cod, sendo ele o código que identificada a parada dentro da API.
http://mobile-l.sitbus.com.br:6060/siumobile-ws-v01/rest/ws/buscarDadosParada/$codParada/0/retornoJSONPontosItinerario
A resposta será
- sucesso - Bool
- paradas - Array de Parada
a Parada (nesse contexto) é especificada como
- cod - Int Identificação da Parada na API
- siu - String Identificação da Parada na BHTrans
- x - Double Longitude
- y - Double Latitude
- desc - String Nome da Parada
{
"sucesso": true,
"paradas": [
{
"cod": 99154,
"siu": "",
"x": -43.94596,
"y": -19.955252,
"desc": "AVE ARTHUR BERNARDES, 1490"
}
]
}A partir do cod de uma Parada obtido através da busca por localização ou itinerário, é possível utilizar o recurso buscarPrevisoes e o parâmetro para receber as previsões de tal Parada.
http://mobile-l.sitbus.com.br:6060/siumobile-ws-v01/rest/ws/buscarPrevisoes/$codParada/0/retornoJSON
A resposta será
- sucesso - Bool
- previsoes - Array de Ônibus
- horaConsulta - String de DateTime (America/Sao_Paulo)
e cada Ônibus é especificado como
- sgLin - String Número da Linha na BHTrans
- prev - String Previsão
- tpAcess - Int Ônibus Acessível
- cor - Int Cor do Ônibus
- numVeicGestor - String Opcional - Identificação do Veículo
- apelidoLinha - String Nome da linha/Destinos
- codItinerario - Int Código para rastreamento
A informações como sgLin, prev, tpAcess, cores e apelidoLinha foram especificadas no início deste documento. O numVeicGestor é o número do veículo, cada ônibus possui um identificador único e só é exibido quando o ônibus está em rota. O codItinerario é utilizado para solicitar o recurso de rastreamento do veículo.
É importante lembrar que são recebidas apenas as previsões menores que 30 minutos.
{
"sucesso": true,
"previsoes": [{
"sgLin": "51",
"prev": "6 Minutos",
"tpAcess": 6,
"cor": 4,
"numVeicGestor": "20440",
"apelidoLinha": "EST.PAMPULHA/CENTRO/HOSPITAIS",
"codItinerario": 48155
}, {
"sgLin": "5250",
"prev": "SAÍDA: 19:00",
"tpAcess": 0,
"cor": 4,
"apelidoLinha": "VIA AREA CENTRAL",
"codItinerario": 48622
}],
"horaConsulta": "27/05/2018 18:34:18"
}Utilizando o mesmo codParada de identificação de Parada e com o recurso retornaLinhasQueAtendemParada é possível receber a lista de linhas que atendem à aquela Parada.
http://mobile-l.sitbus.com.br:6060/siumobile-ws-v01/rest/ws/retornaLinhasQueAtendemParada/$codParada/0/retornoJSON
A resposta será
- sucesso - Bool
- mensagem - String Desconhecido
- linha - Array de Linha
e cada Linha (nesse contexto) é definida como
- cod_linha - Int Identificação da Linha na API
- num_linha - String Número da Linha na BHTrans
- descricao - String Nome da linha/Destinos
- cor - Int Cor do Padrão Ônibus
Note que esta é a única resposta em que o existe o identificador de Linha nomeado como cod_linha.
{
"sucesso": true,
"mensagem": "",
"linhas": [
{
"cod_linha": 591,
"num_linha": "8203",
"descricao": "RENASCENCA/BURITIS",
"cor": 4
},
{
"cod_linha": 598,
"num_linha": "8208",
"descricao": "SANTA CRUZ / UNI-ESTORIL",
"cor": 4
}
]
}O quadro de horário está disponível a partir do recurso retornaQroLinha e requer o parâmetro codLinha, sendo ele o código da Linha, identificado cod ou cod_linha em requisições anteriores. Fique atento aos identificadores.
http://mobile-l.sitbus.com.br:6060/siumobile-ws-v01/rest/ws/retornaQroLinha/$codLinha/0/retornoJSON
A resposta será
- sucesso - Bool
- qros - String de Horários
e cada Horário é definido como
- origem - String Origem do Ônibus [Identificador]
- horario - String Horário
- tipoDia - String Itinerário [Identificador]
Nesse caso existem dois identificadores, sendo eles a Origem e o Itinerário. É importante filtrar os resultados a partir deles. Existem vários Itinerários para cada Origem. Por exemplo, podemos ter a Origem Castelo e o Itinerário Sábado, sendo assim os horários de "Sábado" para todo os Ônibus que partem da Origem "Castelo".
Exemplo de Resposta
{
"sucesso": true,
"qros": [
{
"origem": "RENASCENCA",
"horario": "04:10",
"tipoDia": "Dia Útil"
},
{
"origem": "SANTA EFIGENIA",
"horario": "13:45",
"tipoDia": "SÁBADO DE CARNAVAL"
}
]
}Existe na API a possibilidade de solicitar uma SubLinha de uma Linha, mas não foi encontrada a real necessidade do uso desse recurso. É possível solicitar os dados atráves do recurso retornaSublinhasDaLinha e utilizando codLinha como o código de identificação de uma linha.
http://mobile-l.sitbus.com.br:6060/siumobile-ws-v01/rest/ws/retornaSublinhasDaLinha/$codLinha/0/retornoSublinhasJSON
A resposta será
- sucesso - Bool
- subLinhas - Array de SubLinhas
e uma SubLinha é definida como
- cod - Int Identificação da Linha na API
- sgl - String Número da Linha na BHTrans
- nom - String Nome da linha/Destinos
{
"sucesso": true,
"subLinhas": [
{
"cod": 1315,
"sgl": "8203",
"nom": "RENASCENÇA/BURITIS"
}
]
}O primeiro passo para criar o mapa de rastreamento do veículos é obter as coordenadas de todo o trajeto de Itinerário, assim você pode posicionar o veículo em cima de sua rota e entender o destino. Para obter esses dados é necessário solicitar o recurso buscarItinerario com o codItinerario obtido anteriormente (e o 0).
http://mobile-l.sitbus.com.br:6060/siumobile-ws-v01/rest/ws/buscarItinerario/$codItinerario/0/retornoJSONItinerario
A resposta será
- sucesso - Bool
- itinerarios - Array de Localizações
e cada Localização é definida como
- coordX - Double Longitude
- coordY - Double Latitude
É importante destacar a Parada em que o usuário solicitou a visualização no mapa e sua localização atual, assim ele pode se localizar e visualizar sua distância até o veículo ou Parada.
Veja esta screenshot para entender como é feito o traçado no aplicativo oficial. Utilizando uma API de mapas é possível traçar toda a rota do ônibus, do seu início ao fim do trajeto.
As atualizações do aplicativo costumam ser a cada 10 ou 15 segundos.
{
"sucesso": true,
"itinerarios": [
{
"coordX": -43.967765,
"coordY": -19.841984
},
{
"coordX": -43.967792,
"coordY": -19.841935
}
]
}O metodo retornaVeiculosMapa é de fato o mais interessante desde documento. É necessário utilizar o codItinerario, mesmo parâmetro utilizado para buscar os dados completos do Itinerário no recurso anteiror.
http://mobile-l.sitbus.com.br:6060/siumobile-ws-v01/rest/ws/retornaVeiculosMapa/$codItinerario/0/retornoJSONVeiculos
A resposta será
- sucesso - Bool
- mensagem - String Desconhecido
- veiculos - Array de Veículos
e um Veículo é definido como
- lat - Double Latitude
- long - Double Longitude
- cor - Int Cor - Ver Tabela
- descricao - String Número da Linha na BHTrans
- numVeicGestor - String Número do Veículo
- flagAnimacao - Bool Desconhecido
O Array de Veículos retornará todos os veículos daquela linha e trajeto que estão em rota, mas é importante que você destaque o veículo que o usuário selecionou a partir das previsões. O identificador para esse destaque é o numVeicGestor.
As localizações recebidas para cada veículo sempre ficam em cima do traçado feito no recurso de buscarItinerario, exceto em caso de alterações na rota.
As atualizações de localizações costumam ser a cada 10 ou 15 segundos, e o mapa mostra todos os veículos, incluindo aqueles que estão com previsão maior que 30 minutos.
{
"sucesso": true,
"mensagem": "",
"veiculos": [{
"lat": -19.881715,
"long": -43.944941,
"cor": 8,
"descricao": "8203",
"numVeicGestor": "40414",
"flagAnimacao": "true"
}, {
"lat": -19.970213,
"long": -43.964717,
"cor": 4,
"descricao": "8203",
"numVeicGestor": "40399",
"flagAnimacao": "true"
}]
}Percebi essa requisição uma única vez e não pude identificá-la. Informações abaixo.
http://mobile-l.sitbus.com.br:6060/siumobile-ws-v01/rest/ws/registraUsoSistema/120180512011044695/1.18.2/registraUsoSistemaOK
{
"sucesso": true
}Bruno Armanelli, brunoarmanelli@me.com
[Pesquisa de Dados e Documentação - SIU Mobile] by Bruno Armanelli licensed under CC BY-NC-ND