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