api

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 4, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CircuitBreakerThreshold = 5
	CircuitBreakerResetTime = 30 * time.Second
)
View Source 
const (
	BaseURL        = "https://api.irail.be/v1"
	DefaultTimeout = 60 * time.Second
	UserAgent      = "irail-cli (https://github.com/dedene/irail-cli)"
)
View Source 
const (
	DefaultRequestsPerSecond = 10
	DefaultBurstSize         = 10
)
View Source 
const (
	MaxRateLimitRetries   = 1
	Max5xxRetries         = 0
	RateLimitBaseDelay    = 500 * time.Millisecond
	ServerErrorRetryDelay = 1 * time.Second
)

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	StatusCode int
	Message    string
	Details    string
}

APIError represents an error from the iRail API.

func (*APIError) Error 

func (e *APIError) Error() string

type Alert 

type Alert struct {
	ID          string `json:"id"`
	Header      string `json:"header"`
	Description string `json:"description"`
	Lead        string `json:"lead"`
	Link        string `json:"link"`
	StartTime   string `json:"startTime"`
	EndTime     string `json:"endTime"`
}

Alert represents a disturbance or planned work.

type AlertsContainer 

type AlertsContainer struct {
	Number string  `json:"number"`
	Alert  []Alert `json:"alert"`
}

AlertsContainer wraps the alert array.

type Arrival 

type Arrival struct {
	ID                string      `json:"id"`
	Delay             string      `json:"delay"`
	Station           string      `json:"station"`
	StationInfo       Station     `json:"stationinfo"`
	Time              string      `json:"time"`
	Vehicle           string      `json:"vehicle"`
	VehicleInfo       VehicleInfo `json:"vehicleinfo"`
	Platform          string      `json:"platform"`
	PlatformInfo      Platform    `json:"platforminfo"`
	Canceled          string      `json:"canceled"`
	Arrived           string      `json:"arrived"`
	IsExtra           string      `json:"isExtra"`
	ArrivalConnection string      `json:"arrivalConnection"`
}

Arrival represents a train arrival at a station.

type ArrivalsContainer 

type ArrivalsContainer struct {
	Number  string    `json:"number"`
	Arrival []Arrival `json:"arrival"`
}

ArrivalsContainer wraps the arrivals array.

type CircuitBreaker 

type CircuitBreaker struct {
	// contains filtered or unexported fields
}

func NewCircuitBreaker 

func NewCircuitBreaker() *CircuitBreaker

func (*CircuitBreaker) IsOpen 

func (cb *CircuitBreaker) IsOpen() bool

func (*CircuitBreaker) RecordFailure 

func (cb *CircuitBreaker) RecordFailure() bool

func (*CircuitBreaker) RecordSuccess 

func (cb *CircuitBreaker) RecordSuccess()

type CircuitBreakerError 

type CircuitBreakerError struct{}

CircuitBreakerError indicates the circuit breaker is open.

func (*CircuitBreakerError) Error 

func (e *CircuitBreakerError) Error() string

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the iRail API client.

func NewClient 

func NewClient(lang string) *Client

NewClient creates a new iRail API client.

func (*Client) GetComposition 

func (c *Client) GetComposition(ctx context.Context, id string) (*CompositionResponse, error)

GetComposition fetches the composition of a train.

func (*Client) GetConnections 

func (c *Client) GetConnections(ctx context.Context, from, to string, date, time string, arriveBy bool, results int) (*ConnectionsResponse, error)

GetConnections fetches connections between two stations.

func (*Client) GetDisturbances 

func (c *Client) GetDisturbances(ctx context.Context) (*DisturbancesResponse, error)

GetDisturbances fetches current service disturbances.

func (*Client) GetLiveboard 

func (c *Client) GetLiveboard(ctx context.Context, station string, arrivals bool, date, time string) (*LiveboardResponse, error)

GetLiveboard fetches departures or arrivals for a station.

func (*Client) GetStations 

func (c *Client) GetStations(ctx context.Context) (*StationsResponse, error)

GetStations fetches all stations.

func (*Client) GetVehicle 

func (c *Client) GetVehicle(ctx context.Context, id string, date string) (*VehicleResponse, error)

GetVehicle fetches information about a specific vehicle/train.

func (*Client) SetLanguage 

func (c *Client) SetLanguage(lang string)

SetLanguage sets the language for API requests.

type Composition 

type Composition struct {
	Segments []Segment `json:"segment"`
}

Composition represents train composition data.

type CompositionResponse 

type CompositionResponse struct {
	Version     string      `json:"version"`
	Timestamp   string      `json:"timestamp"`
	Composition Composition `json:"composition"`
}

CompositionResponse is the response from /composition endpoint.

type Connection 

type Connection struct {
	ID        string          `json:"id"`
	Departure ConnectionStop  `json:"departure"`
	Arrival   ConnectionStop  `json:"arrival"`
	Duration  string          `json:"duration"`
	Vias      ViasContainer   `json:"vias"`
	Occupancy Occupancy       `json:"occupancy"`
	Alerts    AlertsContainer `json:"alerts"`
}

Connection represents a journey between two stations.

type ConnectionStop 

type ConnectionStop struct {
	Delay               string      `json:"delay"`
	Station             string      `json:"station"`
	StationInfo         Station     `json:"stationinfo"`
	Time                string      `json:"time"`
	Vehicle             string      `json:"vehicle"`
	VehicleInfo         VehicleInfo `json:"vehicleinfo"`
	Platform            string      `json:"platform"`
	PlatformInfo        Platform    `json:"platforminfo"`
	Canceled            string      `json:"canceled"`
	Direction           Direction   `json:"direction"`
	Left                string      `json:"left"`
	Arrived             string      `json:"arrived"`
	Walking             string      `json:"walking"`
	DepartureConnection string      `json:"departureConnection"`
}

ConnectionStop represents a departure or arrival stop in a connection.

type ConnectionsResponse 

type ConnectionsResponse struct {
	Version    string       `json:"version"`
	Timestamp  string       `json:"timestamp"`
	Connection []Connection `json:"connection"`
}

ConnectionsResponse is the response from /connections endpoint.

type Departure 

type Departure struct {
	ID                  string      `json:"id"`
	Delay               string      `json:"delay"`
	Station             string      `json:"station"`
	StationInfo         Station     `json:"stationinfo"`
	Time                string      `json:"time"`
	Vehicle             string      `json:"vehicle"`
	VehicleInfo         VehicleInfo `json:"vehicleinfo"`
	Platform            string      `json:"platform"`
	PlatformInfo        Platform    `json:"platforminfo"`
	Canceled            string      `json:"canceled"`
	Left                string      `json:"left"`
	IsExtra             string      `json:"isExtra"`
	DepartureConnection string      `json:"departureConnection"`
	Occupancy           Occupancy   `json:"occupancy"`
}

Departure represents a train departure from a station.

type DeparturesContainer 

type DeparturesContainer struct {
	Number    string      `json:"number"`
	Departure []Departure `json:"departure"`
}

DeparturesContainer wraps the departures array.

type Direction 

type Direction struct {
	Name string `json:"name"`
}

Direction indicates the train's direction.

type Disturbance 

type Disturbance struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	Description string `json:"description"`
	Link        string `json:"link"`
	Type        string `json:"type"`
	Timestamp   string `json:"timestamp"`
	Attachment  string `json:"attachment"`
}

Disturbance represents a service disruption.

type DisturbancesResponse 

type DisturbancesResponse struct {
	Version     string        `json:"version"`
	Timestamp   string        `json:"timestamp"`
	Disturbance []Disturbance `json:"disturbance"`
}

DisturbancesResponse is the response from /disturbances endpoint.

type LiveboardResponse 

type LiveboardResponse struct {
	Version     string              `json:"version"`
	Timestamp   string              `json:"timestamp"`
	Station     string              `json:"station"`
	StationInfo Station             `json:"stationinfo"`
	Departures  DeparturesContainer `json:"departures"`
	Arrivals    ArrivalsContainer   `json:"arrivals"`
}

LiveboardResponse is the response from /liveboard endpoint.

type MaterialType 

type MaterialType struct {
	ParentType  string `json:"parent_type"`
	SubType     string `json:"sub_type"`
	Orientation string `json:"orientation"`
}

MaterialType indicates the type of rolling stock.

type NotFoundError 

type NotFoundError struct {
	Resource string
	ID       string
}

NotFoundError indicates a resource was not found.

func (*NotFoundError) Error 

func (e *NotFoundError) Error() string

type Occupancy 

type Occupancy struct {
	URI  string `json:"@id"`
	Name string `json:"name"`
}

Occupancy indicates expected train occupancy.

type Platform 

type Platform struct {
	Name   string `json:"name"`
	Normal string `json:"normal"`
}

Platform contains platform information.

type RateLimitError 

type RateLimitError struct {
	RetryAfter int
}

RateLimitError indicates the API rate limit was exceeded.

func (*RateLimitError) Error 

func (e *RateLimitError) Error() string

type RetryTransport 

type RetryTransport struct {
	Base           http.RoundTripper
	MaxRetries429  int
	MaxRetries5xx  int
	BaseDelay      time.Duration
	CircuitBreaker *CircuitBreaker
	RateLimiter    *TokenBucket
}

RetryTransport wraps an http.RoundTripper with retry logic for rate limits (429) and server errors (5xx).

func NewRetryTransport 

func NewRetryTransport(base http.RoundTripper) *RetryTransport

func (*RetryTransport) RoundTrip 

func (t *RetryTransport) RoundTrip(req *http.Request) (*http.Response, error)

type Segment 

type Segment struct {
	Origin      Station            `json:"origin"`
	Destination Station            `json:"destination"`
	Composition SegmentComposition `json:"composition"`
}

Segment represents a portion of the train's journey.

type SegmentComposition 

type SegmentComposition struct {
	Source string `json:"source"`
	Units  Units  `json:"unit"`
}

SegmentComposition contains the actual train units.

type Station 

type Station struct {
	ID           string `json:"id"`
	URI          string `json:"@id"`
	Name         string `json:"name"`
	StandardName string `json:"standardname"`
	LocationX    string `json:"locationX"`
	LocationY    string `json:"locationY"`
}

Station represents a Belgian railway station.

type StationsResponse 

type StationsResponse struct {
	Version   string    `json:"version"`
	Timestamp string    `json:"timestamp"`
	Station   []Station `json:"station"`
}

StationsResponse is the response from /stations endpoint.

type Stop 

type Stop struct {
	ID                     string   `json:"id"`
	Station                string   `json:"station"`
	StationInfo            Station  `json:"stationinfo"`
	Time                   string   `json:"time"`
	Delay                  string   `json:"delay"`
	Platform               string   `json:"platform"`
	PlatformInfo           Platform `json:"platforminfo"`
	Canceled               string   `json:"canceled"`
	DepartureDelay         string   `json:"departureDelay"`
	ArrivalDelay           string   `json:"arrivalDelay"`
	DepartureCanceled      string   `json:"departureCanceled"`
	ArrivalCanceled        string   `json:"arrivalCanceled"`
	Left                   string   `json:"left"`
	Arrived                string   `json:"arrived"`
	IsExtraStop            string   `json:"isExtraStop"`
	ScheduledDepartureTime string   `json:"scheduledDepartureTime"`
	ScheduledArrivalTime   string   `json:"scheduledArrivalTime"`
}

Stop represents a stop on a vehicle's route.

type StopsContainer 

type StopsContainer struct {
	Number string `json:"number"`
	Stop   []Stop `json:"stop"`
}

StopsContainer wraps the stops array.

type TokenBucket 

type TokenBucket struct {
	// contains filtered or unexported fields
}

TokenBucket implements a token bucket rate limiter.

func NewDefaultTokenBucket 

func NewDefaultTokenBucket() *TokenBucket

NewDefaultTokenBucket creates a rate limiter with default settings.

func NewTokenBucket 

func NewTokenBucket(requestsPerSecond, burst int) *TokenBucket

NewTokenBucket creates a new rate limiter.

func (*TokenBucket) TryAcquire 

func (tb *TokenBucket) TryAcquire() bool

TryAcquire attempts to acquire a token without blocking.

func (*TokenBucket) Wait 

func (tb *TokenBucket) Wait(ctx context.Context) error

Wait blocks until a token is available or the context is cancelled.

type Unit 

type Unit struct {
	ID                         string       `json:"id"`
	MaterialType               MaterialType `json:"materialType"`
	HasToilets                 string       `json:"hasToilets"`
	HasAirco                   string       `json:"hasAirco"`
	HasHeating                 string       `json:"hasHeating"`
	HasBikeSection             string       `json:"hasBikeSection"`
	HasPrmSection              string       `json:"hasPrmSection"`
	SeatsFirstClass            string       `json:"seatsFirstClass"`
	SeatsSecondClass           string       `json:"seatsSecondClass"`
	LengthInMeter              string       `json:"lengthInMeter"`
	TractionType               string       `json:"tractionType"`
	CanPassToNextUnit          string       `json:"canPassToNextUnit"`
	TractionPosition           string       `json:"tractionPosition"`
	HasPrmToilet               string       `json:"hasPrmToilet"`
	HasTables                  string       `json:"hasTables"`
	HasSecondClassOutlets      string       `json:"hasSecondClassOutlets"`
	HasFirstClassOutlets       string       `json:"hasFirstClassOutlets"`
	HasSemiPrivateCompartments string       `json:"hasSemiPrivateCompartments"`
}

Unit represents a single carriage/car.

type Units 

type Units struct {
	Number string `json:"number"`
	Unit   []Unit `json:"unit"`
}

Units wraps the unit array.

type VehicleInfo 

type VehicleInfo struct {
	Name      string `json:"name"`
	ShortName string `json:"shortname"`
	Number    string `json:"number"`
	Type      string `json:"type"`
	URI       string `json:"@id"`
	LocationX string `json:"locationX"`
	LocationY string `json:"locationY"`
}

VehicleInfo contains vehicle/train information.

type VehicleResponse 

type VehicleResponse struct {
	Version     string         `json:"version"`
	Timestamp   string         `json:"timestamp"`
	Vehicle     string         `json:"vehicle"`
	VehicleInfo VehicleInfo    `json:"vehicleinfo"`
	Stops       StopsContainer `json:"stops"`
}

VehicleResponse is the response from /vehicle endpoint.

type Via 

type Via struct {
	ID          string         `json:"id"`
	Arrival     ConnectionStop `json:"arrival"`
	Departure   ConnectionStop `json:"departure"`
	TimeBetween string         `json:"timeBetween"`
	Station     string         `json:"station"`
	StationInfo Station        `json:"stationinfo"`
	Vehicle     string         `json:"vehicle"`
	VehicleInfo VehicleInfo    `json:"vehicleinfo"`
	Direction   Direction      `json:"direction"`
}

Via represents a transfer point in a connection.

type ViasContainer 

type ViasContainer struct {
	Number string `json:"number"`
	Via    []Via  `json:"via"`
}

ViasContainer wraps the vias array.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.