tfl

README

TfL Unified API in Go

This is a Go wrapper that provides access to the Transport for London (TfL) Unified API. It allows developers to retrieve information about TfL services, such as tube lines, bus routes, and bike points.

Installation

To install the TfL Go Library, use the following command:

go get github.com/jamesalexatkin/tfl-golanglang

Authentication

You'll need to register for an API key from TfL in order to use this API.

Example usage

TODO

Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.

If making a pull request, please ensure that the linter checks pass (by running make lint) and that tests still work. You'll need to grab an API key to run integration tests locally. Set the two environment variables (APP_ID and APP_KEY) accordingly, then run make test-all to run unit and integration tests.

License

This library is available under the MIT License. See the LICENSE file for more information.

Documentation

Index

• Constants
• type AccidentDetail
• type ActiveServiceType
• type AdditionalProperty
• type AffectedRoute
• type AffectedStop
• type Bay
• type BikePointOccupancy
• type CarParkOccupancy
• type Casualty
• type ChargeConnectorOccupancy
• type Client
  • func New(appID string, appKey string) *Client
  • func (c *Client) GetAccidentDetails(ctx context.Context, year int) ([]AccidentDetail, error)
  • func (c *Client) GetActiveServiceTypes(ctx context.Context) ([]ActiveServiceType, error)
  • func (c *Client) GetAllBikePoints(ctx context.Context) ([]Place, error)
  • func (c *Client) GetAllCarParkOccupancies(ctx context.Context) ([]CarParkOccupancy, error)
  • func (c *Client) GetAllChargeConnectorOccupancies(ctx context.Context) ([]ChargeConnectorOccupancy, error)
  • func (c *Client) GetArrivalPredictionsForMode(ctx context.Context, mode string, count int) ([]Prediction, error)
  • func (c *Client) GetBikePoint(ctx context.Context, bikePointID string) (*Place, error)
  • func (c *Client) GetBikePointOccupancies(ctx context.Context, bikePointIDs []string) ([]BikePointOccupancy, error)
  • func (c *Client) GetCarParkOccupancy(ctx context.Context, carParkID string) (*CarParkOccupancy, error)
  • func (c *Client) GetChargeConnectorOccupancy(ctx context.Context, chargeConnectorIDs []string) ([]ChargeConnectorOccupancy, error)
  • func (c *Client) GetLineStatusByMode(ctx context.Context, modes []string) ([]Status, error)
  • func (c *Client) GetVehiclePredictions(ctx context.Context, vehicleIDs []string) ([]Prediction, error)
  • func (c *Client) SearchBikePoint(ctx context.Context, searchQuery string) ([]Place, error)
• type Crowding
• type Disruption
• type HTTPError
  • func (e HTTPError) Error() string
• type Line
• type LineGroup
• type LineModeGroup
• type LineStatus
• type PassengerFlow
• type Place
• type Prediction
• type PredictionTiming
• type Property
• type RouteSection
• type RouteSectionNaptanEntrySequence
• type ServiceType
• type Status
• type StopPoint
• type TrainLoading
• type ValidityPeriod
• type Vehicle
• type Via

Constants

const APIBaseURL = "https://api.tfl.gov.uk"

APIBaseURL is the base URL domain for the TfL API.

Types

type AccidentDetail

type AccidentDetail struct {
	ID         int        `json:"id"`
	Lat        float64    `json:"lat"`
	Lon        float64    `json:"lon"`
	Location   string     `json:"location"`
	Date       time.Time  `json:"date"`
	Severity   string     `json:"severity"`
	Borough    string     `json:"borough"`
	Casualties []Casualty `json:"casualties"`
	Vehicles   []Vehicle  `json:"vehicles"`
}

AccidentDetail provides information about an accident.

type ActiveServiceType

type ActiveServiceType struct {
	Mode        string `json:"mode"`
	ServiceType string `json:"serviceType"`
}

ActiveServiceType represents the type of service currently active for a mode of transport.

type AdditionalProperty

type AdditionalProperty struct {
	Category        string `json:"category"`
	Key             string `json:"key"`
	SourceSystemKey string `json:"sourceSystemKey"`
	Value           string `json:"value"`
	Modified        string `json:"modified"`
}

AdditionalProperty represents additional metadata.

type AffectedRoute

type AffectedRoute struct {
	ID                              string                            `json:"id"`
	LineID                          string                            `json:"lineId"`
	RouteCode                       string                            `json:"routeCode"`
	Name                            string                            `json:"name"`
	LineString                      string                            `json:"lineString"`
	Direction                       string                            `json:"direction"`
	OriginationName                 string                            `json:"originationName"`
	DestinationName                 string                            `json:"destinationName"`
	Via                             Via                               `json:"via"`
	IsEntireRouteSection            bool                              `json:"isEntireRouteSection"`
	ValidTo                         time.Time                         `json:"validTo"`
	ValidFrom                       time.Time                         `json:"validFrom"`
	RouteSectionNaptanEntrySequence []RouteSectionNaptanEntrySequence `json:"routeSectionNaptanEntrySequence"`
}

AffectedRoute represents a route affected by a disruption.

type AffectedStop

type AffectedStop struct {
	NaptanID             string          `json:"naptanId"`
	PlatformName         string          `json:"platformName"`
	Indicator            string          `json:"indicator"`
	StopLetter           string          `json:"stopLetter"`
	Modes                []string        `json:"modes"`
	IcsCode              string          `json:"icsCode"`
	SmsCode              string          `json:"smsCode"`
	StopType             string          `json:"stopType"`
	StationNaptan        string          `json:"stationNaptan"`
	AccessibilitySummary string          `json:"accessibilitySummary"`
	HubNaptanCode        string          `json:"hubNaptanCode"`
	Lines                []Line          `json:"lines"`
	LineGroup            []LineGroup     `json:"lineGroup"`
	LineModeGroups       []LineModeGroup `json:"lineModeGroups"`
	FullName             string          `json:"fullName"`
	NaptanMode           string          `json:"naptanMode"`
	Status               bool            `json:"status"`
	IndividualStopID     string          `json:"individualStopId"`
	ID                   string          `json:"id"`
	URL                  string          `json:"url"`
	CommonName           string          `json:"commonName"`
	Distance             float64         `json:"distance"`
	PlaceType            string          `json:"placeType"`
	AdditionalProperties []Property      `json:"additionalProperties"`
	Children             []StopPoint     `json:"children"`
	ChildrenUrls         []string        `json:"childrenUrls"`
	Lat                  float64         `json:"lat"`
	Lon                  float64         `json:"lon"`
}

AffectedStop represents a stop affected by a disruption.

type Bay

type Bay struct {
	BayType  string `json:"bayType"`
	BayCount int    `json:"bayCount"`
	Free     int    `json:"free"`
	Occupied int    `json:"occupied"`
}

Bay represents an individual parking bay in a car park.

type BikePointOccupancy

type BikePointOccupancy struct {
	ID                 string `json:"id"`
	Name               string `json:"name"`
	BikesCount         string `json:"bikesCount"`
	EmptyDocks         string `json:"emptyDocks"`
	TotalDocks         string `json:"totalDocks"`
	StandardBikesCount string `json:"standardBikesCount"`
	EBikesCount        string `json:"eBikesCount"`
}

BikePointOccupancy represents the occupancy of a bike point.

type CarParkOccupancy

type CarParkOccupancy struct {
	ID                string `json:"id"`
	Bays              []Bay  `json:"bays"`
	Name              string `json:"name"`
	CarParkDetailsURL string `json:"carParkDetailsUrl"`
}

CarParkOccupancy represents the occupancy of a car park.

type Casualty

type Casualty struct {
	Age      int    `json:"age"`
	Class    string `json:"class"`
	Severity string `json:"severity"`
	Mode     string `json:"mode"`
	AgeBand  string `json:"ageBand"`
}

Casualty represents a casualty that occurred during an accident.

type ChargeConnectorOccupancy

type ChargeConnectorOccupancy struct {
	ID                  string `json:"id"`
	SourceSystemPlaceID string `json:"sourceSystemPlaceId"`
	Status              string `json:"status"`
}

ChargeConnectorOccupancy represents the occupancy of a charge connector.

type Client

type Client struct {
	AppID      string
	AppKey     string
	APIBaseURL string
	HTTPClient *http.Client
}

Client provides a mechanism to interact with the TfL API.

func New

func New(appID string, appKey string) *Client

New returns a new client.

func (*Client) GetAccidentDetails

func (c *Client) GetAccidentDetails(ctx context.Context, year int) ([]AccidentDetail, error)

GetAccidentDetails gets all accident details for accidents occurring in the specified year.

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/AccidentStats/AccidentStats_Get

func (*Client) GetActiveServiceTypes

func (c *Client) GetActiveServiceTypes(ctx context.Context) ([]ActiveServiceType, error)

GetActiveServiceTypes returns the service type active for a mode. Currently only supports tube.

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/Mode/Mode_GetActiveServiceTypes

func (*Client) GetAllBikePoints

func (c *Client) GetAllBikePoints(ctx context.Context) ([]Place, error)

GetAllBikePoints gets all bike point locations. The Place object has an addtionalProperties array which contains the nbBikes, nbDocks and nbSpaces numbers which give the status of the BikePoint. A mismatch in these numbers i.e. nbDocks - (nbBikes + nbSpaces) != 0 indicates broken docks.

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/BikePoint/BikePoint_GetAll

func (*Client) GetAllCarParkOccupancies

func (c *Client) GetAllCarParkOccupancies(ctx context.Context) ([]CarParkOccupancy, error)

GetAllCarParkOccupancies returns the occupancy for all car parks that have occupancy data.

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/Occupancy/Occupancy_Get_0

func (*Client) GetAllChargeConnectorOccupancies

func (c *Client) GetAllChargeConnectorOccupancies(ctx context.Context) ([]ChargeConnectorOccupancy, error)

GetAllChargeConnectorOccupancies gets the occupancy for all charge connectors.

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/Occupancy/Occupancy_GetAllChargeConnectorStatus

func (*Client) GetArrivalPredictionsForMode

func (c *Client) GetArrivalPredictionsForMode(ctx context.Context, mode string, count int) ([]Prediction, error)

GetArrivalPredictionsForMode gets the next arrival predictions for all stops of a given mode.

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/Mode/Mode_Arrivals

func (*Client) GetBikePoint

func (c *Client) GetBikePoint(ctx context.Context, bikePointID string) (*Place, error)

GetBikePoint gets the bike point with the given ID.

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/BikePoint/BikePoint_Get

func (*Client) GetBikePointOccupancies

func (c *Client) GetBikePointOccupancies(ctx context.Context, bikePointIDs []string) ([]BikePointOccupancy, error)

GetBikePointOccupancies gets the occupancy for bike points.

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/Occupancy/Occupancy_GetBikePointsOccupancies

func (*Client) GetCarParkOccupancy

func (c *Client) GetCarParkOccupancy(ctx context.Context, carParkID string) (*CarParkOccupancy, error)

GetCarParkOccupancy returns the occupancy for a car park with a given ID.

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/Occupancy/Occupancy_Get

func (*Client) GetChargeConnectorOccupancy

func (c *Client) GetChargeConnectorOccupancy(
	ctx context.Context,
	chargeConnectorIDs []string,
) (
	[]ChargeConnectorOccupancy,
	error,
)

GetChargeConnectorOccupancy gets the occupancy for a charge connector with a given ID (sourceSystemPlaceId).

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/Occupancy/Occupancy_GetChargeConnectorStatus

func (*Client) GetLineStatusByMode

func (c *Client) GetLineStatusByMode(ctx context.Context, modes []string) ([]Status, error)

GetLineStatusByMode gets the line status of all lines for the given modes.

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/Line/Line_StatusByMode

func (*Client) GetVehiclePredictions

func (c *Client) GetVehiclePredictions(ctx context.Context, vehicleIDs []string) ([]Prediction, error)

GetVehiclePredictions gets the predictions for a given list of vehicle IDs.

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/Vehicle/Vehicle_Get

func (*Client) SearchBikePoint

func (c *Client) SearchBikePoint(ctx context.Context, searchQuery string) ([]Place, error)

SearchBikePoint searches for bike stations by their name, a bike point's name often contains information about the name of the street or nearby landmarks, for example. Note that the search result does not contain the PlaceProperties i.e. the status or occupancy of the BikePoint, to get that information you should retrieve the BikePoint by its id on /BikePoint/id.

https://api.tfl.gov.uk/swagger/ui/index.html?url=/swagger/docs/v1#!/BikePoint/BikePoint_Search

type Crowding

type Crowding struct {
	PassengerFlows []PassengerFlow `json:"passengerFlows"`
	TrainLoadings  []TrainLoading  `json:"trainLoadings"`
}

Crowding represents how crowded a particular vehicle is.

type Disruption

type Disruption struct {
	Category            string          `json:"category"`
	Type                string          `json:"type"`
	CategoryDescription string          `json:"categoryDescription"`
	Description         string          `json:"description"`
	Summary             string          `json:"summary"`
	AdditionalInfo      string          `json:"additionalInfo"`
	Created             time.Time       `json:"created"`
	LastUpdate          time.Time       `json:"lastUpdate"`
	AffectedRoutes      []AffectedRoute `json:"affectedRoutes"`
	AffectedStops       []AffectedStop  `json:"affectedStops"`
	ClosureText         string          `json:"closureText"`
}

Disruption represents a particular disruption.

type HTTPError

type HTTPError struct {
	Status string
	Body   string
}

HTTPError can be returned to represent a failed HTTP call.

func (HTTPError) Error

func (e HTTPError) Error() string

type Line

type Line struct {
	ID        string   `json:"id"`
	Name      string   `json:"name"`
	URI       string   `json:"uri"`
	FullName  string   `json:"fullName"`
	Type      string   `json:"type"`
	Crowding  Crowding `json:"crowding"`
	RouteType string   `json:"routeType"`
	Status    string   `json:"status"`
	MotType   string   `json:"motType"`
	Network   string   `json:"network"`
}

Line represents a particular line on a mode of transport.

type LineGroup

type LineGroup struct {
	NaptanIDReference string   `json:"naptanIdReference"`
	StationAtcoCode   string   `json:"stationAtcoCode"`
	LineIDentifier    []string `json:"lineIdentifier"`
}

LineGroup represents national metadata identifying the group of the line.

type LineModeGroup

type LineModeGroup struct {
	ModeName       string   `json:"modeName"`
	LineIdentifier []string `json:"lineIdentifier"`
}

LineModeGroup represents the mode group of a line.

type LineStatus

type LineStatus struct {
	ID                        int              `json:"id"`
	LineID                    string           `json:"lineId"`
	StatusSeverity            int              `json:"statusSeverity"`
	StatusSeverityDescription string           `json:"statusSeverityDescription"`
	Reason                    string           `json:"reason"`
	Created                   string           `json:"created"`  // Uses different format to time.Time
	Modified                  string           `json:"modified"` // Uses different format to time.Time
	ValidityPeriods           []ValidityPeriod `json:"validityPeriods"`
	Disruption                Disruption       `json:"disruption"`
}

LineStatus represents the status of a particular line.

type PassengerFlow

type PassengerFlow struct {
	TimeSlice string `json:"timeSlice"`
	Value     int    `json:"value"`
}

PassengerFlow represents the flow of passengers at a particular time.

type Place

type Place struct {
	ID                   string               `json:"id"`
	URL                  string               `json:"url"`
	CommonName           string               `json:"commonName"`
	Distance             int                  `json:"distance"`
	PlaceType            string               `json:"placeType"`
	AdditionalProperties []AdditionalProperty `json:"additionalProperties"`
	Children             []Place              `json:"children"`
	ChildrenURLs         []string             `json:"childrenUrls"`
	Lat                  float64              `json:"lat"`
	Lon                  float64              `json:"lon"`
}

Place represents a place managed by TfL. This includes things like bike points, coach bays and speed cameras.

type Prediction

type Prediction struct {
	ID                  string           `json:"id"`
	OperationType       int              `json:"operationType"`
	VehicleID           string           `json:"vehicleId"`
	NaptanID            string           `json:"naptanId"`
	StationName         string           `json:"stationName"`
	LineID              string           `json:"lineId"`
	LineName            string           `json:"lineName"`
	PlatformName        string           `json:"platformName"`
	Direction           string           `json:"direction"`
	Bearing             string           `json:"bearing"`
	DestinationNaptanID string           `json:"destinationNaptanId"`
	DestinationName     string           `json:"destinationName"`
	Timestamp           time.Time        `json:"timestamp"`
	TimeToStation       int              `json:"timeToStation"`
	CurrentLocation     string           `json:"currentLocation"`
	Towards             string           `json:"towards"`
	ExpectedArrival     time.Time        `json:"expectedArrival"`
	TimeToLive          time.Time        `json:"timeToLive"`
	ModeName            string           `json:"modeName"`
	Timing              PredictionTiming `json:"timing"`
}

Prediction represents the expected arrival of a vehicle (e.g. a tube or bus) on its way to a destination.

type PredictionTiming

type PredictionTiming struct {
	CountdownServerAdjustment string `json:"countdownServerAdjustment"`
	Source                    string `json:"source"`
	Insert                    string `json:"insert"`
	Read                      string `json:"read"`
	Sent                      string `json:"sent"`
	Received                  string `json:"received"`
}

PredictionTiming represents the timing metadata for a `Prediction`.

type Property

type Property struct {
	Category        string    `json:"category"`
	Key             string    `json:"key"`
	SourceSystemKey string    `json:"sourceSystemKey"`
	Value           string    `json:"value"`
	Modified        time.Time `json:"modified"`
}

Property represents an additional property for a station or stop point.

type RouteSection

type RouteSection struct {
	RouteCode       string    `json:"routeCode"`
	Name            string    `json:"name"`
	Direction       string    `json:"direction"`
	OriginationName string    `json:"originationName"`
	DestinationName string    `json:"destinationName"`
	Originator      string    `json:"originator"`
	Destination     string    `json:"destination"`
	ServiceType     string    `json:"serviceType"`
	ValidTo         time.Time `json:"validTo"`
	ValidFrom       time.Time `json:"validFrom"`
}

RouteSection represents a particular section of a route.

type RouteSectionNaptanEntrySequence

type RouteSectionNaptanEntrySequence struct {
	Ordinal   int       `json:"ordinal"`
	StopPoint StopPoint `json:"stopPoint"`
}

RouteSectionNaptanEntrySequence represents the NaPTAN information for a route section.

type ServiceType

type ServiceType struct {
	Name string `json:"name"`
	URI  string `json:"uri"`
}

ServiceType represents a type of service for a mode of transport.

type Status

type Status struct {
	ID            string         `json:"id"`
	Name          string         `json:"name"`
	ModeName      string         `json:"modeName"`
	Disruptions   []Disruption   `json:"disruptions"`
	Created       string         `json:"created"`  // Uses different format to time.Time
	Modified      string         `json:"modified"` // Uses different format to time.Time
	LineStatuses  []LineStatus   `json:"lineStatuses"`
	RouteSections []RouteSection `json:"routeSections"`
	ServiceTypes  []ServiceType  `json:"serviceTypes"`
	Crowding      Crowding       `json:"crowding"`
}

Status represents the status for a mode of transport.

type StopPoint

type StopPoint struct {
	NaptanID             string          `json:"naptanId"`
	PlatformName         string          `json:"platformName"`
	Indicator            string          `json:"indicator"`
	StopLetter           string          `json:"stopLetter"`
	Modes                []string        `json:"modes"`
	IcsCode              string          `json:"icsCode"`
	SmsCode              string          `json:"smsCode"`
	StopType             string          `json:"stopType"`
	StationNaptan        string          `json:"stationNaptan"`
	AccessibilitySummary string          `json:"accessibilitySummary"`
	HubNaptanCode        string          `json:"hubNaptanCode"`
	Lines                []Line          `json:"lines"`
	LineGroup            []LineGroup     `json:"lineGroup"`
	LineModeGroups       []LineModeGroup `json:"lineModeGroups"`
	FullName             string          `json:"fullName"`
	NaptanMode           string          `json:"naptanMode"`
	Status               bool            `json:"status"`
	IndividualStopID     string          `json:"individualStopId"`
	ID                   string          `json:"id"`
	URL                  string          `json:"url"`
	CommonName           string          `json:"commonName"`
	Distance             float64         `json:"distance"`
	PlaceType            string          `json:"placeType"`
	AdditionalProperties []Property      `json:"additionalProperties"`
	Children             []StopPoint     `json:"children"`
	ChildrenUrls         []string        `json:"childrenUrls"`
	Lat                  float64         `json:"lat"`
	Lon                  float64         `json:"lon"`
}

StopPoint represents a stopping point on a line.

type TrainLoading

type TrainLoading struct {
	Line              string `json:"line"`
	LineDirection     string `json:"lineDirection"`
	PlatformDirection string `json:"platformDirection"`
	Direction         string `json:"direction"`
	NaptanTo          string `json:"naptanTo"`
	TimeSlice         string `json:"timeSlice"`
	Value             int    `json:"value"`
}

TrainLoading represents the loading of a train going in a particular direction.

type ValidityPeriod

type ValidityPeriod struct {
	FromDate time.Time `json:"fromDate"`
	ToDate   time.Time `json:"toDate"`
	IsNow    bool      `json:"isNow"`
}

ValidityPeriod represents a period of time for which a status is valid.

type Vehicle

type Vehicle struct {
	Type string `json:"type"`
}

Vehicle represents a vehicle.

type Via

type Via struct {
	Ordinal   int       `json:"ordinal"`
	StopPoint StopPoint `json:"stopPoint"`
}

Via represents a stop point that a route can go via (e.g. Northern Line via Charing Cross).