Model Reference¶

Note

Every attribute can be None when no data is available, unless noted otherwise.

Base Models¶

All choo models are based upon one of the following three base classes that build on top of each other.

class Serializable¶

All models are Serializables. See Model Serialization for more information.

validate()¶: Checks if all attributes have valid values. Raises an exception if the object is not valid. This method is also called by serialize().

serialize()¶

Serializes this object in a JSON-encodable format. This is a shortcut for Serializable.serialize(serializable).

Return type:	the serialized object

classmethod serialize(obj)

Serializes the given instance of this model in a JSON-encodable format, using typed serialization if the given object is an instance of a submodel.

>>> stop.serialize()
{…}
>>> Stop.serialize(stop) == stop.serialize()
True
>>> Location.serialize(stop)
['Stop', {…}]
>>> Location.serialize(stop)[1] == stop.serialize()
True

Parameters:	obj – A serialized representation of a choo object
Return type:	the serialized object

classmethod unserialize(data)¶

Unserializes an object of this model or one of its child classes from a JSON-encodable format. Always use the same model for unserialization as you used for serialization.

Parameters:	data – A serialized representation of an object of this model or one of its submodels.
Return type:	the unserialized object

class Searchable¶

An Serializable that can be searched for. You can pass it to the API and to get its complete information.

All subclasses have a Request and a Results subclass. You can pass the and instance of the Request subclass to the API to get search results in a Results subclass.

class Request(Serializable)¶: A request template for this Model with lots of possible search criteria that can be set.

class Searchable.Results(Serializable)¶

A list (of Request-Results) of instances of this object. Those lists can have match scores.

You can just iterate over this object to get its contents.

scored(obj)¶: Returns an iterator over tuples of (results, score).

filter(request)¶: Remove all objects that do not match the given Request.

filtered(request)¶: Returns a new Results instance with all objects that do not match the given Request removed.

Note

For serialization, the list of results is stored in the property results as a list. Each element of this list is a two-element list containing the serialized result and the match score.

Please note that the serialized result is typed serialized if the Model has submodels (e.g. Location, which has Stop etc…)

class Collectable¶

A Searchable that can be collected. It has an ID and it really exists and is not some kind of data construct.

source¶: Source Network of this object. All APIs set this attribute, but it is not mandatory for input.

id¶: ID of this object (as str) in the source network.

Locations¶

class GeoLocation¶

Submodel of :py:class:`Serializable`.

Abstract base class for everything that has a fixed position.

lat¶: latitude as float

lon¶: longitude as float

class Coordinates(lat, lon)¶

Submodel of :py:class:`GeoLocation`.

A Model just geographic coordinate.

You can cast Coordinates to tuple if needed:

>>> tuple(Coordinates(51.445555, 7.017253))
(51.445555, 7.017253)

class Platform(stop, name=None, full_name=None)¶

Submodel of :py:class:`Collectable` and :py:class:`GeoLocation`.

An place where rides stop (e.g. Gleis 7). It belongs to one Stop.

ifopt¶: The globally unique ID of this Platform according to Identification of Fixed Objects in Public Transport supported by some APIs.

stop¶: Not None. The Stop this platform belongs to.

name¶: The name of this Platform (e.g. 7 or 2b).

full_name¶: The full name of this Platform (e.g. Bussteig 7 or Gleis 2b)

class Request¶: Submodel of Searchable.Request.

class Platform.Results¶: Submodel of Searchable.Results.

class Location(country=None, city=None, name=None)¶

Submodel of :py:class:`Collectable` and :py:class:`GeoLocation`.

Abstract base class place that is named and not a sublocation like a Platform.

country¶: The country of this location as a two-letter country code.

city¶: The name of the city this location is located in.

name¶: The name of this location. If the city attribute is None this it may also included in the name.

near_stops¶: Other stops near this one as a Stop.Results, if available. You can always search for Stops near a GeoLocation directly using Stop.Request.

class Request¶

Submodel of Searchable.Request.

name¶: A search string for the name of the Location.

city¶: City of the Location.

class Location.Results¶: Submodel of Searchable.Results.

class Stop(country=None, city=None, name=None)¶

Submodel of :py:class:`Location`.

A train station, bus stop, etc. For example: Düsseldorf Hbf.

ifopt¶: The globally unique ID of this Stop according to Identification of Fixed Objects in Public Transport supported by some APIs.

uic¶: The is the international train station id by the International Union of Railways.

full_name¶: The full name of this Stop. Can be just the city and the name, but does’nt have to.

lines¶: The Lines that are available at this stop as a Line.Results object, if available. You can always search for Lines at a Stop using Line.Request.

rides¶: The next rides at this stop as a Ride.Results object, if available. You can always search for Rides at a Stop using Ride.Request.

class Request¶: Submodel of Location.Request.

class Stop.Results¶: Submodel of Location.Results.

class Address(country=None, city=None, name=None)¶

Submodel of :py:class:`Location`.

An address. The name attribute contains the address in one string, but more detailed attributes may be available:

street¶: The name of the street.

number¶: The house number as a string.

class Request¶: Submodel of Location.Request.

class Address.Results¶: Submodel of Location.Results.

class POI(country=None, city=None, name=None)¶

Submodel of :py:class:`Location`.

A Point of Interest.

class Request¶: Submodel of Location.Request.

class POI.Results¶: Submodel of Location.Results.

Rides¶

class Ride(line=None, number=None)¶

Submodel of :py:class:`Collectable`.

A ride is implemented as a list of RidePoint objects and suppors nearly all methods of Python’s native list type.

If you iterate over a Ride each item you get is None or a RidePoint object. Each item that is None stands for n missing stations. It can also mean that the RidePoint before and after the item are in fact the same. To get rid of all None items, pass an incomplete ride to a network API.

You can slice a Ride which will get you a RideSegment that refers to the original ride but always will have the correct boundaries, even if elements between are removed or inserted between them. Slicing with no start or no end point is also supported.

Caution

Slicing a Ride is inclusive! For example, slicing from element 2 to element 5 results in a RideSegment describing the journey between element 2 and element 5, containing 4 elements in total!

time¶
The time at which the ride data was retrieved as ``datetime``.

line¶: Not None. The Line of this Ride.

number¶: The number (train number or similar) of this Ride as a string.

canceled¶: A boolean indicating whether this ride has been canceled.

bike_friendly¶: A boolean indicating whether this is a bike-friendly vehicle.

append(item)¶: Append a RidePoint object (or None).

prepend(item)¶: Prepend a RidePoint object (or None).

insert(position, item)¶: Insert a RidePoint (or None) as the new position position.

remove(item)¶: Remove this RidePoint (not None) from the list.

pop([i])¶: Remove the item at the given position (default: last position) from the list.

index([i])¶: Remove the item at the given position (default: last position) from the list.

You can also use in and del.

Attention

The following attributes are dynamic and can not be set.

path¶
Get the geographic path of the ride as a list of :py:class:`Coordinates`. If you only want to get the path between to stops, just use the :py:class:`RideSegment` property with the same name.: Falls back to just directly connecting the platform or stop coordinates if no other information is available.

Note

For serialization, the property stops is created containing a list of the serialized elements. Each RidePoint element can have the additional property path_to_next containing a list of tupled py:class:Coordinates.

class Request¶: Submodel of Searchable.Request.

class Ride.Results¶: Submodel of Searchable.Results.

class RideSegment¶

*Submodel of :py:class:`TripPart`.*

This class created by slicing Ride objects.

This model is usable in the same way as a Ride. Slicing it will return another RideSegment for the same Ride.

Caution

Slicing a Ride is inclusive! For example, slicing from element 2 to element 5 results in a RideSegment describing the journey between element 2 and element 5, containing 4 elements in total!

ride¶: Not None. The Ride that this object is a segment of.

index([i])¶: Remove the item at the given position (default: last position) from the list.

You can also use in.

Attention

The following attributes are dynamic and can not be set.

path¶
Get the geographic path of the ride segment as a list of :py:class:`Coordinates`.: Falls back to just directly connecting the platform or stop coordinates if no other information is available.

origin¶: The first Stop of this segment. Shortcut for segment[0].stop.

destination¶: The last Stop of this segment. Shortcut for segment[-1].stop.

departure¶: The departure at the first Stop of this segment as LiveTime. Shortcut for segment[0].departure.

arrival¶: The arrival at the last Stop of this segment as LiveTime. Shortcut for segment[-1].arrival.

Note

For serialization, the boundaries are given as integer indexes as properties origin and destination. Each one can be missing if the boundary is not set. (e.g. ride[5:])

Don’t forget that Ride slicing is inclusive (see above)!

class RidePoint(platform, arrival=None, departure=None)¶

Submodel of :py:class:`Serializable`.

Time and place of a Ride stopping at a Platform.

platform¶: Not None. The Platform.

arrival¶: The arrival time of the Ride as LiveTime.

departure¶: The departure time of the Ride as LiveTime.

passthrough¶: A boolean indicating whether the ride does not actually stop at this Stop but pass through it.

LiveTime¶

class LiveTime(time, delay=None)¶

Submodel of :py:class:`Serializable`.

A point in time with optional real time data.

Parameters:	time – The originally planned time as a datetime.datetime object. delay – The (expected) delay as a datetime.timedelta object if known.

time¶: Not None. The originally planned time as a datetime.datetime object.

delay¶: The (expected) delay as a datetime.timedelta object or None. Please note that a zero delay is not the same as None. None stands for absence of real time information.

Attention

The following attributes are dynamic and can not be set.

is_live¶: True if there is real time data available. Shortcut for delay is not None

expected_time¶: The (expected) actual time as a datetime.datetime object if real time data is available, otherwise the originally planned time.

Lines¶

class Line(linetype=None)¶

Submodel of :py:class:`Collectable`.

A group of Rides (e.g. Bus Line 495). Every Ride belongs to one Line.

linetype¶: Not None. The LineType of this Line.

product¶: The product name, for example InterCity, Hamburg-Köln-Express or Niederflurbus.

name¶: Not None The long name of the Line, for example Rhein-Haardt-Express RE2.

shortname¶: Not None The short name of the Line, for example RE2.

route¶: The route description.

first_stop¶: The first Stop of this Line. Rides may start at a later station.

last_stop¶: The last Stop of this Line. Rides may end at a earlier station.

network¶: The name of the network this Line natively belongs to.

operator¶: The name of the company that operates this line.

class Request¶: Submodel of Searchable.Request.

class Line.Results¶: Submodel of Searchable.Results.

Note

For serialization, the string representation is used for linetype.

class LineType(name)¶

Submodel of :py:class:`Serializable`.

Each Line has a line type. A line type has one of the values (empty string), train, train.local, train.longdistance, train.longdistance.highspeed, urban, metro, tram, bus, bus.regional, bus.city, bus.express, bus.longdistance, suspended, ship, dialable, or other.

An empty string means that it can be anyone of the other linetypes, The linetype bus means that it could be any of the bus-subtypes. The reason for this is that not all networks differentiate between some subtyes (e.g. bus types). See the network reference for which linetypes it may output.

All identical linetypes are the same instance:

>>> LineType('bus') is LineType('bus')
True

To compare against a linetype, use the in operator. Be aware that this operator is not transitive!

>>> linetype = LineType('bus.express')
>>> linetype in LineType('bus')
True
>>> LineType('bus') in linetype
False

>>> LineType('bus') in LineType('')
True
>>> LineType('') in LineType('bus')
False
>>> LineType('bus') in LineType('bus')
True

You can cast a LineType to string if needed:

>>> str(LineType('train.local'))
'train.local'

class LineTypes(include=('', ), exclude=())¶

Submodel of :py:class:`Serializable`.

A selector for LineType object. It is defined as a list of included line types and a list of excluded linetypes. By default, all line types are included.

>>> LineType('bus') in LineTypes()
True

>>> LineType('bus') in LineTypes(exclude=('bus', ))
False
>>> LineType('bus.express') in LineTypes(exclude=('bus', ))
False
>>> LineType('bus') in LineTypes(exclude=('bus.express', ))
True
>>> LineType('bus.express') in LineTypes(exclude=('bus.express', ))
False

>>> LineType('train') in LineTypes(include=('bus', ), exclude=('bus.express', ))
False
>>> LineType('bus') in LineTypes(include=('bus', ), exclude=('bus.express', ))
True
>>> LineType('bus.express') in LineTypes(include=('bus', ), exclude=('bus.express', ))
False

You can modify the selector using the following methods:

include(*linetypes)¶

Parameters:	linetypes – one or more line types as string or `LineType`

Make sure that the given line types and all of their subtypes are matched by the selector.

exclude(*linetypes)¶

Parameters:	linetypes – one or more line types as string or `LineType`

Make sure that the given line types and all of their subtypes are not matched by the selector.

Note

For serialization, the properties included and excluded are created, each one containing a list of string representation of line types.

Trips¶

class Trip¶

Submodel of :py:class:`Searchable`.

A connection from a GeoLocation to another GeoLocation.

It consists of a list of TripPart objects. Just iterate over it to get its elements.

time¶: The fetching time of this object as a datetime object. This is relevant to know how up to date the contained real time data (delays, cancellation, platform changes, etc.) is. All APIs set this attribute, but it is not mandatory for input.

tickets¶: TicketList of available tickets for this trip.

Attention

The following attributes are dynamic and can not be set.

origin¶: The start GeoLocation of this trip.

destination¶: The end GeoLocation of this trip.

departure¶: The departure at the first GeoLocation of this trip as LiveTime. (If there are leading Way objects they need to have the duration attribute set in order for this to work)

arrival¶: The arrival at the last GeoLocation of this trip as LiveTime. (If there are trailing Way objects they need to have the duration attribute set in order for this to work)

linetypes¶: The line types that occur in this trip as LineTypes.

wayonly¶: A boolean indicating whether this Trip only consists of Way objects.

changes¶: The number of changes in this trip (number of RideSegments minus one with a minimum of zero)

bike_friendly¶: False if at least one Ride that is part of this trip is not bike friendly. True if all of them are. None if there is no bike friendly information for all rides but those that have the information are bike friendly.

Note

For serialization, the property parts is created containing the list of typed serialized trip parts.

class Request¶

Submodel of Searchable.Request.

origin¶: Not None. The start GeoLocation of the trip.

destination¶: Not None. The end GeoLocation of the trip.

departure¶

The minimum departure time as LiveTime or datetime.datetime.

If both times are None the behaviour is as if you would have set the departure time to the current time right before sending the request. (Default: None)

arrival¶: The latest allowed arrival as LiveTime or datetime.datetime. (Default: None)

linetypes¶: The line types that are allowed as LineTypes. (Default: all)

max_changes¶: The maximum number of changes allowed or None for no limit. (Default: None)

with_bike¶: Whether a bike should be taken along. (Default: False)

wheelchair¶: Whether to allow only vehicles that support wheelchairs. (Default: False)

low_floor_only¶: Whether to allow only low floor vehicles. (Default: False)

allow_solid_stairs¶: Whether to allow solid stairs. (Default: True)

allow_escalators¶: Whether to allow escalators. (Default: True)

allow_elevators¶: Whether to allow elevators. (Default: True)

waytype_origin¶: Waytype at the beginning of the trip. (Default: walk)

waytype_via¶: Waytype at changes or ways during the trip. (Default: walk)

waytype_destination¶: Waytype at the end of the trip. (Default: walk)

wayduration_origin¶: Maximum duration of a way at the beginning of the trip as a datetime.timedelta. (Default: 10 minutes)

wayduration_via¶: Maximum duration of changes of ways during the trip as a datetime.timedelta. (Default: 10 minutes)

wayduration_destination¶: Maximum duration of a way at the end of the trip as a datetime.timedelta. (Default: 10 minutes)

class Trip.Results¶

Submodel of Searchable.Results.

origin¶: Not None. The start GeoLocation of the trip.

destination¶: Not None. The end GeoLocation of the trip.

class TripPart¶

Submodel of :py:class:`Serializable`.

Abstract base Class for Trip parts

Ways¶

class Way(origin: Location, destination: Location, distance: int=None)¶

Submodel of :py:class:`TripPart`.

Individual transport (walk, bike, taxi…) with no schedule. Used for example to get from a Address to a Stop and for changes but also for trips that are faster by foot.

waytype¶: Not None. The WayType of this way.

origin¶: Not None. The start point Location.

destination¶: Not None. The end point Location.

distance¶: The distance in meters as int.

duration¶: The expected duration as datetime.timedelta.

path¶: The path as a list of Coordinates.

events¶: Events on the way (e.g. taking escalators upwards) as a (ordered) list of WayEvent.

Note

For serialization, the string representation is used for linetype and the WayEvent objects in events.

The property path is a list of tuple representations of Coordinates.

class WayType(name)¶

Submodel of :py:class:`Serializable`.

Each Way has a line type. A Linetype has one of the values walk, bike, car, taxi.

All identical way types are the same instance:

>>> WayType('walk') is WayType('walk')
True

You can cast a WayType to string if needed:

>>> str(WayType('walk'))
'walk'

class WayEvent(name, direction)¶

Submodel of :py:class:`Serializable`.

A way Way events one of the names stairs, escalator or elevator and one of the directions up or down.

All identical way types are the same instance:

>>> WayType('escalator', 'down') is WayType('escalator', 'down')
True

You can cast a WayEvent to string or tuple if needed:

>>> str(WayEvent('escalator, 'down'))
'escalator.down'
>>> tuple(WayEvent('escalator, 'down'))
('escalator', 'down')

Attention

The following attributes are dynamic and can not be set.

name¶: Not None. stairs, escalator or elevator

direction¶: Not None. up or down

Tickets¶

class TicketList(all_types: bool=True)¶

Submodel of :py:class:`Serializable`.

A list of tickets.

currency¶: Not None. The name or abbreviation of the currency.

level_name¶: How a level is named at this network.

single¶: Not None. The single ticket as TicketData.

bike¶: The single ticket as TicketData.

other¶: Not None. Other available tickets as a dictionary with the name of the tickets as keys and TicketData objects as values.

Submodels of Serializable.

class TicketData(authority=None, level=None, price=None, price_child=None)¶

Submodel of :py:class:`Serializable`.

Information about a ticket.

authority¶: The name of the authority selling this ticket.

level¶: The level of this ticket, e.g. A or something similar, depending on the network

price¶: Not None. The price of this ticket as float.

price_child¶: The children’s price for this ticket if this ticket is not a ticket for children only but has a different price for children.