# friendly public transport format

## references

In order to be able to use this format in both static data *and* API responses, you may choose whether to reference an item by its `id` or inline the item as an object. Take this stop as an example:

```js
{
	type: 'stop',
	id: '1234',
	name: 'Bus Terminal A',
	station: '123' // this references a `station` object
}
```

You may also inline the `station` if that's more convenient:

```js
{
	type: 'stop',
	id: '1234',
	name: 'Bus Terminal A',
	station: { // inline `station` object
		type: 'station',
		id: '123',
		name: 'Copenhagen Central Station'
	}
}
```

## `location` objects

A `location` object is used by other items to indicate their locations.

```js
{
	type: 'location', // required
	name: 'Reichstagsgebäude', // optional
	address: 'Platz der Republik 1, 11011 Berlin', // optional

	longitude: 13.4, // optional
	latitude: 52.5, // optional
	altitude: 130.5 // optional, in meters
}
```

If the `latitude` field is specified in a `location` object, the `longitude` field must also be specified, and vice-versa.

## item types

### `station`

A station is a larger building or area that can be identified by a name. It is usually represented by a single node on a public transport map. Whereas a `stop` usually specifies a location, a `station` often is a broader area that may span across multiple levels or buildings.

```js
{
	type: 'station', // required
	id: '123456', // unique, required
	name: 'Berlin Hauptbahnhof', // official non-abbreviated name, required
	// todo: other names
	location: { // location object, optional
		// … see above
	},
	regions: [ // region ids or region objects, see the section on 'region's, optional
		'1234', '2345'
	]
}
```

### `stop`

A stop is a single small point or structure at which vehicles stop. A stop always belongs to a station. It may for example be a sign, a basic shelter or a railway platform.

If the underlying data source does not allow such a fine-grained distinction, use `station`s instead.

```js
{
	type: 'stop', // required
	id: '12345678', // unique, required
	station: '123456', // station id or station object, required
	name: 'Berlin Hauptbahnhof (tief)', // official non-abbreviated name, required
	// todo: other names
	location: { // location object, optional
		// … see above
	}
}
```

### `region`

A `region` is a group of `station`s, for example a metropolitan area or a geographical or cultural region.

In many urban areas, there are several long-distance train & bus stations, all distinct but well-connected through local public transport. It makes sense to keep them as `station`s, because they may still have individual `stop`s, but clustering them enables more advanced routing information.

A `station` can be part of multiple `region`s.

```js
{
	type: 'region', // required
	id: '1234', // unique, required
	name: 'Bretagne', // official non-abbreviated name, required
	// todo: other names
	stations: [ // station ids or station objects, required
		'123456', '234567'
	]
}
```

### `line`

```js
{
	type: 'line', // required
	id: '123', // unique, required
	name: 'ICE 599', // official non-abbreviated name, required
	mode: 'train', // see section on modes, required
	subMode: …, // reserved for future use
	// todo: color, ...
	routes: [], // array of route ids or route objects
	operator: '123456', // operator id or operator object
}
```

### `route`

A route represents a single set of stations, of a single `line`.

For a very consistent subway service, there may be one route for each direction. Planned detours, trains stopping early and additional directions would have their own route.

```js
{
	type: 'route', // required
	id: '1234', // unique, required
	line: '123', // line id or line object, required,
	mode: 'bus', // see section on modes, overrides `line` mode, e.g. for replacements services
	subMode: …, // reserved for future use
	stops: [ // array of stop/station ids or objects, required
		'12345678',
		'87654321'
	]
}
```

### `schedule`

*Note:* There are many ways to format schedules of public transport routes. This one tries to balance the amount of data and consumability. It is specifically geared towards urban public transport, with frequent trains and homogenous travels.

```js
{
	type: 'schedule', // required
	id: '12345', // unique, required
	route: '1234', // route id or object, required
	mode: 'bus', // see section on modes, overrides `route`/`line` mode, e.g. for replacements services
	subMode: …, // reserved for future use
	sequence: [
		// seconds relative to departure at first station/stop
		// in 1-to-1 relation to `route` stops
		{
			arrival: -30 // optional, when the vehicle enters the route
			// The departure at the first stop must be 0.
			departure: 0 // required
		},
		{
			arrival: 50, // optional
			departure: 70 // required
		}
		{
			arrival: 120, // The arrival at the last stop is required.
			departure: 150 // optional, when the vehicle leaves the route
		}
	],
	starts: [ // array of Unix timestamps, required
		1488379661, // start time of the trip
		1488379761,
		1488379861,
		1488379961
	]
}
```

### `operator`

```js
{
	type: 'operator', // required
	id: 'sncf', // unique, required
	name: 'Société nationale des chemins de fer français' // official non-abbreviated name, required
}
```

### `stopover`

A `stopover` represents a vehicle stopping at a stop/station at a specific time.

```js
{
	type: 'stopover', // required

	// - stop/station id or object
	// - required
	stop: '12345-678',

	// - ISO 8601 string (with stop/station timezone)
	// - required if `departure` is null
	arrival: '2017-03-17T15:00:00+02:00',

	// - seconds relative to scheduled arrival
	// - optional
	arrivalDelay: -45,

	arrivalPlatform: '4-1', // string, optional

	// - ISO 8601 string (with stop/station timezone)
	// - required if `arrival` is null
	departure: '2017-03-16T20:00:00+01:00',

	// - seconds relative to scheduled departure
	// - optional
	departureDelay: 120,

	departurePlatform: null, // string, optional
}
```

### `journey`

A `journey` is a computed set of directions to get from A to B at a specific time. It would typically be the result of a route planning algorithm.

```js
{
	type: 'journey', // required
	id: '12345', // unique, required
	legs: [ // array of objects, required
		{
			// - station/stop/location id or object
			// - required
			origin: '12345678',

			// station/stop/location id or object
			// - required
			destination: '87654321',

			// - ISO 8601 string (with origin timezone)
			// - required
			departure: '2017-03-16T20:00:00+01:00',

			// - seconds relative to scheduled departure
			// - optional
			departureDelay: 120,

			departurePlatform: '4-1', // string, optional

			// - ISO 8601 string (with destination timezone)
			// - required
			arrival: '2017-03-17T15:00:00+02:00',

			// - seconds relative to scheduled arrival
			// - optional
			arrivalDelay: -45,

			arrivalPlatform: '9', // string, optional

			// - array of stopover objects
			// - optional
			stopovers: […],

			// - schedule id or object
			// - optional
			schedule: '1234',

			// - see section on modes
			// - overrides `schedule`'s `mode`
			mode: 'train',

			subMode: …, // reserved for future use

			public: true, // is it publicly accessible?

			// - operator id or object
			// - overrides `schedule`'s `operator`
			operator: 'sncf'

			// use this if pricing information is available for specific legs
			price: { // optional
				amount: 12.50, // number, required
				currency: 'EUR' // ISO 4217 code, required
			}
		}
		// …
	],
	price: { // optional
		amount: 19.95, // number, required
		currency: 'EUR' // ISO 4217 code, required
	}
}
```

The `departureDelay` and `arrivalDelay` fields should only contain a value if realtime data or a prognosis based on realtime data is actually available.

## modes

As discussed in [#4](https://github.com/public-transport/friendly-public-transport-format/issues/4), we decided to have two fields `mode` and `subMode`.

The following list shows all possible values for a `mode` property. For consumers to be able to use `mode` meaningfully, we will keep this list very short.

- `train`
- `bus`
- `watercraft`
- `taxi`
- `gondola`
- `aircraft`
- `car`
- `bicycle`
- `walking`

In order to convey more details, we will add the `subMode` field in the future. It will differentiate means of transport in a more fine-grained way, in order to enable consumers to provide more context and a better service.