API Comboios

---

v1

Tipo de resposta

A API REST retorna a informação pretendida incorporada num objecto JSON com a seguinte estrutura:

• success: booleano - Verdadeiro caso o pedido tenha sido efectuado correctamente. O código da resposta HTTP é definida de acordo com a situação.
• timestamp: timestamp - Data e hora a que o pedido foi processado, no formato ISO 8601 com offset UTC (e.g. 2018-12-01T12:25:44.214+00:00).
• cached: booleano - Verdadeiro caso os dados devolvidos tenham sido obtidos a partir de cache.
• expiry: timestamp - Data e hora a que a informação em cache expira. Caso não haja informação em cache, este parâmetro vem a null.
• error: string - Mensagem descritiva do erro ocorrido no pedido. Caso não haja erro, este parâmetro vem a null.
• data: objecto - Informação do pedido. Caso tenha ocorrido um erro, este parâmetro vem a null.

Métodos

A API disponibiliza os seguintes métodos, acessíveis através do protocolo HTTP GET:

1. stations
2. stations-id
3. departures
4. departures-date
5. arrivals
6. arrivals-date

• stations: /api/v1/stations

  Retorna um objecto JSON com a lista de todas as estações disponíveis na aplicação. Esta lista contém os identificadores (IDs) e os nomes das estações.

  Exemplo: /api/v1/stations

  					{
  	"success": true,
  	"timestamp": "2018-12-01T12:25:44.214+00:00",
  	"cached": false,
  	"expiry": null,
  	"error": null,
  	"data": {
  		"9401008": "PORTO-SÃO BENTO",
  		"9402006": "PORTO-CAMPANHÃ",
  		"9403004": "CONTUMIL",
  		"9403038": "RIO TINTO",
  		...
  	}
  }
  				

• stations-id: /api/v1/stations/[sid]

  Retorna um objecto JSON com a informação da estação com ID sid.

  Exemplo: /api/v1/stations/9431039

  					{
  	"success": true,
  	"timestamp": "2018-12-01T12:25:44.214+00:00",
  	"cached": false,
  	"expiry": null,
  	"error": null,
  	"data": {
  		"id": 9431039,
  		"name": "LISBOA-ORIENTE"
  	}
  }
  				

• departures: /api/v1/departures/[sid]

  Retorna um objecto JSON com a lista de todas as partidas a para a estação com ID definido em sid. A lista inclui todas as partidas futuras até ao final do presente dia de exploração, incluindo comboios atrasados e suprimidos, conforme e seguinte especificação:

  • Comboios de todos os tipos e sem atrasos nem supressões são sempre mostrados
  • Comboios suburbanos com atraso superior a 2 horas são omitidos
  • Comboios de qualquer tipo suprimidos há mais de 2 horas são omitidos

  O objecto contém a data de exploração a que os dados dizem respeito e um array com os comboios que partem da estação.
  Cada elemento desse array contém a informação relativa a um comboio com partida dessa estação, nomeadamente, o ID do comboio, o seu tipo, data/hora de chegada, data/hora de partida, ID da estação de onde partiu, ID da estação para onde se dirige, nome do operador e estado, que por sua vez contém a descrição do estado (ontime, delayed ou suppressed) e o seu atraso em minutos (0 caso esteja a horas ou suprimido).
  Caso não exista informação disponível para a estação seleccionada é retornado um array vazio.

  Exemplo: /api/v1/departures/9431039

  					{
  	"success": true,
  	"timestamp": "2018-12-01T12:25:44.214+00:00",
  	"cached": false,
  	"expiry": null,
  	"error": null,
  	"data": {
  		"dateOfExploration": "2018-12-01",
  		"trains": [
  			{
  				"id": 16048,
  				"type": "suburban",
  				"arrivalTime": "2018-12-01T23:45:00.000Z",
  				"departureTime": "2018-12-01T23:45:30.000Z",
  				"origin": 9433001,
  				"destination": 9430007,
  				"operator": "CP LISBOA",
  				"status": {
  					"description": "delayed",
  					"delay": 6
  				}
  			},
  			{
  				"id": 4440,
  				"type": "regional",
  				"arrivalTime": "2018-12-02T00:02:30.000Z",
  				"departureTime": "2018-12-02T00:03:30.000Z",
  				"origin": 9440154,
  				"destination": 9430007,
  				"operator": "CP REGIONAL",
  				"status": {
  					"description": "ontime",
  					"delay": 0
  				}
  			},
  			...
  		]
  	}
  }
  				

  Pode ainda ser acrescentado na chamada ao método o parâmetro subonly=true que fará com que a resposta contenha apenas resultados relativos a comboios do tipo suburbano.

  Exemplo: /api/v1/departures/9431039?subonly=true

• departures-id: /api/v1/departures/[sid]/[data]

  Retorna um objecto JSON com a lista de todas as partidas a para a estação com ID definido em sid e para a data em data. Esta data deve ser apresentada no formato AAAA-MM-DD. Pode não haver informação disponível para datas muito distantes no futuro.
  Este método admite a utilização do parâmetro subonly=true.

  O retorno deste método é semelhante ao do método departures.

• arrivals: /api/v1/arrivals/[sid]

  Retorna um objecto JSON com a lista de todas as chegadas a para a estação com ID definido em sid. A lista inclui todas as chegadas futuras até ao final do presente dia de exploração, incluindo comboios atrasados e suprimidos, conforme e seguinte especificação:

  • Comboios de todos os tipos e sem atrasos nem supressões são sempre mostrados
  • Comboios suburbanos com atraso superior a 2 horas são omitidos
  • Comboios de qualquer tipo suprimidos há mais de 2 horas são omitidos
  
  Caso não exista informação disponível para a estação seleccionada é retornado um array vazio.
  Este método admite a utilização do parâmetro subonly=true.

  O retorno deste método é semelhante ao do método departures.

• arrivals-id: /api/v1/arrivals/[sid]/[data]

  Retorna um objecto JSON com a lista de todas as chegadas para a estação com ID definido em sid e para a data em data. Esta data deve ser apresentada no formato AAAA-MM-DD. Pode não haver informação disponível para datas muito distantes no futuro.
  Este método admite a utilização do parâmetro subonly=true.

  O retorno deste método é semelhante ao do método departures.