thgmhz/bus-promise

:oncoming_bus: Biblioteca que busca informações em tempo real da frota de ônibus da SPTrans na cidade de São Paulo.

Bus Promise

Busca informações em tempo real da frota de ônibus da SPTrans na cidade de São Paulo.

Sobre

A SPtrans disponibiliza uma API para consulta de alguns dados, porém outros dados estão disponíveis somente em arquivos .csv que seguem a especificação GTFS (General Transit Feed Specification). O bus-promise é uma biblioteca Javascript (client-side e server-side) feita para facilitar o uso da API e dos arquivos GTFS da SPTrans.

Como funciona

O bus-promise faz requisições na API da SPTrans e no bus-server, um serviço complementar da biblioteca que está hospedado no heroku e responde com os dados dos arquivos GTFS. Dado que a API da SPTrans não oferece suporte a especificação CORS, o bus-server também é um auxiliar para requisições feitas pelo browser. Isso permite a biblioteca funcionar tanto no client-side quanto no server-side.

Como utilizar

Instalação

$ npm install --save bus-promise

Node.js

import * as bus from 'bus-promise'

Browser

Você pode instalar o bus-promise via npm. Ou se preferir pode copiar o script clicando aqui. Os métodos estarão acessíveis através da variável global bus.

Token

A API da SPTrans exige autenticação com um token que você pode obter ao se cadastrar pelo link: http://www.sptrans.com.br/desenvolvedores/.

Autenticação

O método auth() recebe um token e retorna uma Promise com as credentials.

import * as bus from 'bus-promise'

bus.auth('SEU_TOKEN_AQUI')
  .then(console.log)

O método find()

Este é o principal método da biblioteca, você deve usá-lo para realizar buscas pelos seguintes tipos de dados:

• Linhas (lines)
• Linhas por sentido (linesByDirection)
• Trajetos (shapes)
• Paradas (stops)
• Paradas por linha (stopsByLine)
• Corredores (corridors)
• Paradas por corredor (stopsByCorridor)
• Posição dos veículos (vehiclesPosition)
• Previsão de chegada (arrivalForecast)
• Previsão da linha (lineForecast)
• Previsão da parada (stopForecast)
• Empresas

Linhas (lines)

O tipo lines possibilita a consulta pelas linhas de ônibus da cidade de São Paulo.

Aceita o nome da linha ou letreiro displaySign. O valor deve ser passado pelo parâmetro terms como string:

import bus from 'bus-promise'

bus.auth('SEU_TOKEN_AQUI')
  .then(getLines)

function getLines (auth) {
  bus.find({
    auth,
    type: 'lines',
    terms: 'Term. Lapa'
  }).then(console.log)
}

Para obter todas as linhas:

bus.find({
  auth,
  type: 'lines',
  terms: '*'
}).then(console.log)

Resposta

Atributo	Tipo	Descrição
lineId	integer	Código identificador da linha. Este é um código identificador único de cada linha do sistema (por sentido de operação).
shapeId	integer	Código identificador do trajeto. Este código deve ser usado para consultar o trajeto completo do ônibus através do tipo shapes.
circular	bool	Indica se uma linha opera no modo circular (sem um terminal secundário).
displaySign	string	A primeira parte do letreiro numérico da linha.
direction	int	A segunda parte do letreiro numérico da linha, que indica se a linha opera nos modos: base (10), atendimento (21, 23, 32, 41).
type	int	O sentido ao qual a linha atende, onde 1 significa do Terminal Principal (mainDestination) para Terminal Secundário (secondaryDestination) e 2 do Terminal Secundário para Terminal Principal.
mainTerminal	string	O letreiro descritivo da linha no sentido Terminal Principal para Terminal Secundário.
secondaryTerminal	string	O letreiro descritivo da linha no sentido Terminal Secundário para Terminal Principal.

Linhas por sentido (linesByDirection)

O tipo linesDirection possibilita a consulta pelas linhas de ônibus filtrando pelo sentido.

Aceita o nome ou letreiro da linha e o sentido da linha O valor deve ser passado pelos parâmetros terms como string e direction como integer. Os valores aceitos em direction são:

• 1: Terminal Principal para Terminal Secundário
• 2: Terminal Secundário para Terminal Principal

  bus.find({
    auth,
    type: 'linesDirection',
    terms: '8000',
    direction: 1
  }).then(console.log)

Resposta

Atributo	Tipo	Descrição
lineId	integer	Código identificador da linha. Este é um código identificador único de cada linha do sistema (por sentido de operação).
circular	bool	Indica se uma linha opera no modo circular (sem um terminal secundário).
displaySign	string	A primeira parte do letreiro numérico da linha.
direction	int	A segunda parte do letreiro numérico da linha, que indica se a linha opera nos modos: base (10), atendimento (21, 23, 32, 41).
type	int	O sentido ao qual a linha atende, onde 1 significa do Terminal Principal (mainDestination) para Terminal Secundário (secondaryDestination) e 2 do Terminal Secundário para Terminal Principal.
mainTerminal	string	O letreiro descritivo da linha no sentido Terminal Principal para Terminal Secundário.
secondaryTerminal	string	O letreiro descritivo da linha no sentido Terminal Secundário para Terminal Principal.

Trajeto (shapes)

O tipo shapes retorna uma lista com a latitude e longitude de cada rua do trajeto do ônibus.

Aceita o código do trajeto. O valor deve ser passado pelo parâmetro shapeId como integer:

bus.find({
  auth,
  type: 'shapes',
  shapeId: 63468
}).then(console.log)

Resposta

Atributo	Tipo	Descrição
shapeId	integer	Código identificador do trajeto.
lat	string	Latitude daquele ponto do trajeto.
lng	string	Longitude daquele ponto do trajeto.
sequence	string	Número que indica a sequência de cada ponto do trajeto.

Paradas (stops)

O tipo stops possibilita a consulta pelos pontos de parada da cidade de São Paulo.

Aceita o nome da parada ou o endereço de localização. O valor deve ser passado pelo parâmetro terms como string:

bus.find({
  auth,
  type: 'stops',
  terms: 'Av. Mutinga'
}).then(console.log)

Para obter todas as paradas:

bus.find({
  auth,
  type: 'stops',
  terms: '*'
}).then(console.log)

Resposta

Atributo	Tipo	Descrição
stopId	integer	Código identificador da parada.
name	string	Nome da parada.
address	string	Endereço de localização da parada.
lat	string	Informação de latitude da localização da parada.
lng	string	Informação de longitude da localização da parada.

Paradas por linha (stopsByLine)

O tipo stopsByLine realiza uma busca por todos os pontos de parada atendidos por uma determinada linha.

Aceita o código da linha. O valor deve ser passado pelo parâmetro lineId como integer:

bus.find({
  auth,
  type: 'stopsByLine',
  lineId: 34041
}).then(console.log)

Resposta

Atributo	Tipo	Descrição
stopId	integer	Código identificador da parada.
name	string	Nome da parada.
address	string	Endereço de localização da parada.
lat	string	Informação de latitude da localização da parada.
lng	string	Informação de longitude da localização da parada.

Corredores (corridors)

O tipo corridors realiza uma busca por todos os corredores de ônibus da cidade de São Paulo.

bus.find({
  auth,
  type: 'corridors'
}).then(console.log)

Resposta

Atributo	Tipo	Descrição
corridorId	integer	Código identificador do corredor.
name	string	Nome do corredor.

Paradas por corredor (stopsByCorridor)

O tipo stopsByCorridor retorna a lista detalhada de todas as paradas que compõem um determinado corredor.

Aceita o código do corredor. O valor deve ser passado pelo parâmetro corridorId como integer:

bus.find({
  auth,
  type: 'stopsByCorridor',
  corridorId: 8
}).then(console.log)

Resposta

Atributo	Tipo	Descrição
stopId	integer	Código identificador da parada.
name	string	Nome da parada.
address	string	Endereço de localização da parada.
lat	string	Informação de latitude da localização da parada.
lng	string	Informação de longitude da localização da parada.

Posição dos veículos (vehiclesPosition)

O tipo vehiclesPosition retorna a posição exata de cada veículo de qualquer linha de ônibus da SPTrans.

Aceita o código da linha. O valor deve ser passado pelo parâmetro lineId como integer:

bus.find({
  auth,
  type: 'vehiclesPosition',
  lineId: 34041
}).then(console.log)

Resposta

Atributo	Tipo	Descrição
hour	string	Horário de referência em que as informações foram geradas.
lines	array	Relação de linhas localizadas com os atributos abaixo:
lineId	string	Endereço de localização da parada.
displaySign	string	Letreiro completo.
type	int	O sentido ao qual a linha atende, onde 1 significa do Terminal Principal (mainDestination) para Terminal Secundário (secondaryDestination) e 2 do Terminal Secundário para Terminal Principal.
mainTerminal	string	O letreiro descritivo da linha no sentido Terminal Principal para Terminal Secundário.
secondaryTerminal	string	O letreiro descritivo da linha no sentido Terminal Secundário para Terminal Principal.
quantity	integer	Quantidade de veículos localizados.
vehicles	array	Relação de veículos localizados com os atributos abaixo:
prefix	integer	Prefixo do veículo.
accessible	bool	Indica se o veículo é (true) ou não (false) acessível para pessoas com deficiência.
hour	string	Indica o horário universal (UTC) em que a localização foi capturada. Essa informação está no padrão ISO 8601.
lat	string	Informação de latitude da localização do veículo.
lng	string	Informação de longitude da localização do veículo.

Previsão de chegada (arrivalForecast)

O tipo arrivalForecast retorna a previsão de chegada de cada veículo de uma determinada linha e de um determinado ponto de parada, além da localização exata de cada veículo que constar na cadeia de previsões.

Aceita o código da parada e o código da linha. O valor deve ser passado pelos parâmetros stopId e lineId como integer:

bus.find({
  auth,
  type: 'arrivalForecast',
  stopId: 260015039,
  lineId: 34041
}).then(console.log)

Resposta

Atributo	Tipo	Descrição
hour	string	Horário de referência em que as informações foram geradas.
stops	array	Representa um ponto de parada com os atributos abaixo:
stopId	integer	Código identificador da parada.
name	string	Nome da parada.
address	string	Endereço de localização da parada.
lat	string	Informação de latitude da localização da parada.
lng	string	Informação de longitude da localização da parada.
lines	array	Relação de linhas localizadas com os atributos abaixo:
lineId	string	Endereço de localização da parada.
displaySign	string	Letreiro completo.
type	int	O sentido ao qual a linha atende, onde 1 significa do Terminal Principal (mainDestination) para Terminal Secundário (secondaryDestination) e 2 do Terminal Secundário para Terminal Principal.
mainTerminal	string	O letreiro descritivo da linha no sentido Terminal Principal para Terminal Secundário.
secondaryTerminal	string	O letreiro descritivo da linha no sentido Terminal Secundário para Terminal Principal.
quantity	integer	Quantidade de veículos localizados.
vehicles	array	Relação de veículos localizados com os atributos abaixo:
prefix	integer	Prefixo do veículo.
accessible	bool	Indica se o veículo é (true) ou não (false) acessível para pessoas com deficiência.
hour	string	Indica o horário universal (UTC) em que a localização foi capturada. Essa informação está no padrão ISO 8601.
lat	string	Informação de latitude da localização do veículo.
lng	string	Informação de longitude da localização do veículo.

Previsão da linha (lineForecast)

O tipo lineForecast retorna uma lista com a previsão de chegada de cada um dos veículos da linha informada em todos os pontos de parada aos quais que ela atende.

Aceita o código da linha. O valor deve ser passado pelo parâmetro lineId como integer:

bus.find({
  auth,
  type: 'lineForecast',
  lineId: 34041
}).then(console.log)

Resposta

Atributo	Tipo	Descrição
hour	string	Horário de referência em que as informações foram geradas.
stops	array	Representa um ponto de parada com os atributos abaixo:
stopId	integer	Código identificador da parada.
name	string	Nome da parada.
address	string	Endereço de localização da parada.
lat	string	Informação de latitude da localização da parada.
lng	string	Informação de longitude da localização da parada.
vehicles	array	Relação de veículos localizados com os atributos abaixo:
prefix	integer	Prefixo do veículo.
accessible	bool	Indica se o veículo é (true) ou não (false) acessível para pessoas com deficiência.
hour	string	Indica o horário universal (UTC) em que a localização foi capturada. Essa informação está no padrão ISO 8601.
lat	string	Informação de latitude da localização do veículo.
lng	string	Informação de longitude da localização do veículo.

Previsão da parada (stopForecast)

O tipo stopForecast retorna uma lista com a previsão de chegada dos veículos de cada uma das linhas que atendem ao ponto de parada informado.

Aceita o código da parada. O valor deve ser passado pelo parâmetro stopId como integer:

bus.find({
  auth,
  type: 'stopForecast',
  stopId: 260015039
}).then(console.log)

Resposta

Atributo	Tipo	Descrição
hour	string	Horário de referência em que as informações foram geradas.
stops	array	Representa um ponto de parada com os atributos abaixo:
stopId	integer	Código identificador da parada.
name	string	Nome da parada.
address	string	Endereço de localização da parada.
lat	string	Informação de latitude da localização da parada.
lng	string	Informação de longitude da localização da parada.
lines	array	Relação de linhas localizadas com os atributos abaixo:
lineId	string	Endereço de localização da parada.
displaySign	string	Letreiro completo.
type	int	O sentido ao qual a linha atende, onde 1 significa do Terminal Principal (mainDestination) para Terminal Secundário (secondaryDestination) e 2 do Terminal Secundário para Terminal Principal.
mainTerminal	string	O letreiro descritivo da linha no sentido Terminal Principal para Terminal Secundário.
secondaryTerminal	string	O letreiro descritivo da linha no sentido Terminal Secundário para Terminal Principal.
quantity	integer	Quantidade de veículos localizados.
vehicles	array	Relação de veículos localizados com os atributos abaixo:
prefix	integer	Prefixo do veículo.
accessible	bool	Indica se o veículo é (true) ou não (false) acessível para pessoas com deficiência.
hour	string	Indica o horário universal (UTC) em que a localização foi capturada. Essa informação está no padrão ISO 8601.
lat	string	Informação de latitude da localização do veículo.
lng	string	Informação de longitude da localização do veículo.

Empresas (companies)

O tipo companies possibilita a consulta que retorna a relação das empresas operadoras do transporte público na cidade de São Paulo.

  bus.find({
    auth,
    type: 'companies',
  }).then(console.log)

Resposta

Atributo	Tipo	Descrição
hour	string	Horário de referência da geração das informações.
companiesByOperationArea	array	Relação de empresas por área de operação.
companiesByOperationArea.operationCode	integer	Código da área de operação.
companiesByOperationArea.companies	array	Relação de empresas.
companiesByOperationArea.companies.operationAreaCode	integer	Código da área de operação.
companiesByOperationArea.companies.referenceCode	integer	Código de referência da empresa.
companiesByOperationArea.companies.name	string	nome da empresa.

Como contribuir

Para contribuir com o projeto, clique aqui.

Changelog

Para verificar as mudanças da biblioteca acesse changelog, clique aqui.

Contribuidores

@thiamsantos	@drodrigo

Autor

@thiagommedeiros

bus-promise's Issues

Melhorar os Testes

Precisamos responder essas questões:

• Os testes estão consistentes?
• Os nomes unit e integration fazem sentido?
• Os testes estão cobrindo o que deveriam cobrir?
• Como podemos melhorar os testes?

Fique a vontade para comentar ou submeter um pull request.

Add support for new version of API Olho Vivo - v2.1

Parâmetros e métodos em inglês ou português?

Estou com dúvidas se devo manter os parâmetros e métodos em português ou inglês.

Atualmente:

sptrans.find({
    auth,
    tipo: 'linhas',
    termosBusca: 'Term. Lapa'
})

Como ficaria tudo PT:

sptrans.buscar({
    auth,
    tipo: 'linhas',
    termosBusca: 'Term. Lapa'
})

Como ficaria tudo EN:

sptrans.find({
    auth,
    type: 'lines',
    terms: 'Term. Lapa'
})

Usar rollup

Seria interessante usar o rollup no lugar do browserify para gerar o bundle para o browser. O rollup gera um bundle muito menor (em alguns casos cerca de 40% a 60% menor), além de ter uma melhora na performance já que o browser terá menos bytes para fazer o parse. O que você acha @thiagommedeiros?

Add support to GTFS

GTFS files: http://www.sptrans.com.br/desenvolvedores/GTFS.aspx

Allow the Find method to receive an array of 'terms' or 'codes'

The idea is to make it possible to find, for example, several 'paradas' or 'linhas' passing an array of its values.

Melhorar o CONTRIBUTING.md

Precisamos melhorar o CONTRIBUTING.md nos seguintes aspectos:

• Adicionar um tutorial de instalação/configuração da biblioteca;
• Adicionar tutorial de instalação/configuração do bus-server (deve ser um link com o repositório do bus-server);
• Adicionar um tutorial de como abrir um Pull Request e contribuir;
• Criar um template de Pull Request;

Se você identificou alguma outro problema não citado acima, fique a vontade para comentar.

Se você quer contribuir melhorando algum dos itens citado acima, fique a vontade, baixe o projeto, crie uma branch e abra um pull request! =)

.

Adicionar novos métodos da API da SPTrans

Precisamos adicionar os novos métodos da API da SPTrans:

• BuscarLinhaSentido (DONE)
• BuscarParadasPorCorredor (DONE)
• Empresas (DONE)
• PosicaoVeiculos/Linha (DONE)
• Garagem (WIP)
• Velocidade Nas Vias
  • Cidade
  • Corredor
  • OutrasVias

Link da documentação da SPTrans: http://www.sptrans.com.br/desenvolvedores/APIOlhoVivo/Documentacao.aspx

Listar outras APIs de outras cidades

Gostei muito desse bus-promise, se alguém conhecer APIs de outras cidades, coloca aí em baixo pra montar uma lista :)

Sobre o bus-server

https://github.com/thiagommedeiros/bus-server

• Faz sentido o bus-server estar em outro repositório?
• Precisamos criar uma documentação para o bus-server!
• O nome bus-server está bom ou ele confunde os devs?

Normalize the response parameters name to English

Make the Auth method return the credentials as a string

The response parameters should be in English

Need to serialize all response parameters to English.

Alterar nome do projeto

Depois de consultar alguns amigos/desenvolvedores, eu decidi alterar o nome do projeto para bus-promise. O principal motivo é que esse nome reflete melhor a proposta da biblioteca.

Vale ressaltar que desde o início o nome da biblioteca foi inspirado no projeto cep-promise, do meu gestor na Pagar.me (apesar dele não gostar desse termo) Filipe Deschamps (aka Dev Lindo). =)

O que precisa ser feito

• Alterar nome do projeto no package.json;
• Alterar o README.md substituindo sptrans-promise por bus-promise;
• Alterar testes que importam sptrans-promise;
• Renomear repositório no github;
• Renomear projeto no NPM;
• Deprecar o sptrans-promise no NPM.

.

Add browser support

The SPTrans API doesn't support cross-origin requests. Therefore, a way to resolve that problem is to create a heroku service that will receive a request and send it to SPTrans to receive the response data and then send it back to the browser.

Tratamento de erros

• O tratamento de erros está consistente?
• Estamos cobrindo todas as possibilidades?
• Como podemos melhorar o tratamento de erros?