gtfs

package module
v0.1.24 Latest Latest
Warning

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

 Go to latest Published: Dec 1, 2024 License: MIT Imports: 18 Imported by: 1

README

gtfs

This is a Go package for parsing GTFS static and realtime feeds.

The static parser is pretty straightforward and simply maps fields in the GTFS static CSV files to associated Go types.

For realtime parsing this package offers two options. Option 1 is to use the parser and types generated by the protobuf compiler which are available in the proto subpackage. This saves you from having to compile the protobufs yourself.

Option 2 is to use the package's custom parser, which takes the protobuf output from option 1, does a bunch of post-processing, and then outputs the result in standard (non-proto) Go types. This post-processing does useful things like:

  • Converts some data fields to more idiomatic Go types - for example, times are converted from int64 Unix timestamps to time.Time values.

  • Makes the representation of trips and vehicles more explicit. Each trip has a (nullable) pointer to the associated vehicle in the feed, if it exists, and vice-versa.

  • Implements business logic to map data in various GTFS realtime extensions to regular GTFS realtime fields.

Backwards compatibility warning: this package is under active development and backwards incompatible changes are frequently made. We're eventually planning to release a v1.0.0 version, and after that all changes will be backwards compatible and consistent with semantic versioning.

Examples

Parse the GTFS static feed for the New York City Subway:

resp, _ := http.Get("http://web.mta.info/developers/data/nyct/subway/google_transit.zip")
b, _ := io.ReadAll(resp.Body)
staticData, _ := gtfs.ParseStatic(b, gtfs.ParseStaticOptions{})
fmt.Printf("The New York City subway has %d routes and %d stations\n", len(staticData.Routes), len(staticData.Stops))

Parse the GTFS realtime feed for the San Francisco Bay Area BART:

resp, _ := http.Get("http://api.bart.gov/gtfsrt/tripupdate.aspx")
b, _ := io.ReadAll(resp.Body)
realtimeData, _ := gtfs.ParseRealtime(b, &gtfs.ParseRealtimeOptions{})
fmt.Printf("The SF BART currently has %d trains running or scheduled\n", len(realtimeData.Trips))

Performance

The package is designed to be about as fast as possible without resorting to unreadable code. A profiler for the package is in the performance directory.

Static parser

The static parser has been performance optimized somewhat significantly. It takes about 3 seconds to parse the GTFS static data for the NYC buses (45 megabytes compressed, 360 megabytes uncompressed). The rough breakdown is:

  • 30% of the time unzipping the archives (using the archive/zip standard library package).

  • 40% of the time parsing the CSV files into strings (using the encoding/csv standard library package)

  • 30% of the time in this package performing the conversions from strings into types like time.Duration and linking related entities.

Realtime parser

TBD

Documentation

Overview

Package gtfs contains parsers for GTFS static and realtime feeds.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Agency 

type Agency struct {
	Id       string
	Name     string
	Url      string
	Timezone string
	Language string
	Phone    string
	FareUrl  string
	Email    string
}

Agency corresponds to a single row in the agency.txt file.

type Alert added in v0.1.8 

type Alert struct {
	ID               string
	Cause            AlertCause
	Effect           AlertEffect
	ActivePeriods    []AlertActivePeriod
	InformedEntities []AlertInformedEntity
	Header           []AlertText
	Description      []AlertText
	URL              []AlertText
}

type AlertActivePeriod added in v0.1.8 

type AlertActivePeriod struct {
	StartsAt *time.Time
	EndsAt   *time.Time
}

type AlertCause added in v0.1.8 

type AlertCause = gtfsrt.Alert_Cause
const (
	UnknownCause     AlertCause = gtfsrt.Alert_UNKNOWN_CAUSE
	OtherCause       AlertCause = gtfsrt.Alert_OTHER_CAUSE
	TechnicalProblem AlertCause = gtfsrt.Alert_TECHNICAL_PROBLEM
	Strike           AlertCause = gtfsrt.Alert_STRIKE
	Demonstration    AlertCause = gtfsrt.Alert_DEMONSTRATION
	Accident         AlertCause = gtfsrt.Alert_ACCIDENT
	Holiday          AlertCause = gtfsrt.Alert_HOLIDAY
	Weather          AlertCause = gtfsrt.Alert_WEATHER
	Maintenance      AlertCause = gtfsrt.Alert_MAINTENANCE
	Construction     AlertCause = gtfsrt.Alert_CONSTRUCTION
	PoliceActivity   AlertCause = gtfsrt.Alert_POLICE_ACTIVITY
	MedicalEmergency AlertCause = gtfsrt.Alert_MEDICAL_EMERGENCY
)

type AlertEffect added in v0.1.8 

type AlertEffect = gtfsrt.Alert_Effect
const (
	UnknownEffect      AlertEffect = gtfsrt.Alert_UNKNOWN_EFFECT
	NoService          AlertEffect = gtfsrt.Alert_NO_SERVICE
	ReducedService     AlertEffect = gtfsrt.Alert_REDUCED_SERVICE
	SignificantDelays  AlertEffect = gtfsrt.Alert_SIGNIFICANT_DELAYS
	Detour             AlertEffect = gtfsrt.Alert_DETOUR
	AdditionalService  AlertEffect = gtfsrt.Alert_ADDITIONAL_SERVICE
	ModifiedService    AlertEffect = gtfsrt.Alert_MODIFIED_SERVICE
	OtherEffect        AlertEffect = gtfsrt.Alert_OTHER_EFFECT
	StopMoved          AlertEffect = gtfsrt.Alert_STOP_MOVED
	NoEffect           AlertEffect = gtfsrt.Alert_NO_EFFECT
	AccessibilityIssue AlertEffect = gtfsrt.Alert_ACCESSIBILITY_ISSUE
)

type AlertInformedEntity added in v0.1.8 

type AlertInformedEntity struct {
	AgencyID *string
	RouteID  *string
	// If RouteType isn't set, this will be RouteType_Unknown.
	RouteType   RouteType
	DirectionID DirectionID
	TripID      *TripID
	StopID      *string
}

type AlertText added in v0.1.8 

type AlertText struct {
	Text     string
	Language string
}

type BikesAllowed added in v0.1.16 

type BikesAllowed int32

BikesAllowed describes whether bikes are allowed on a scheduled trip.

This is a Go representation of the enum described in the `bikes_allowed` field of `stops.txt`. 

const (
	BikesAllowed_NotSpecified BikesAllowed = 0
	BikesAllowed_Allowed      BikesAllowed = 1
	BikesAllowed_NotAllowed   BikesAllowed = 2
)

func (BikesAllowed) String added in v0.1.16 

func (b BikesAllowed) String() string

type CongestionLevel added in v0.1.14 

type CongestionLevel = gtfsrt.VehiclePosition_CongestionLevel

type CurrentStatus added in v0.1.14 

type CurrentStatus = gtfsrt.VehiclePosition_VehicleStopStatus

type DirectionID 

type DirectionID uint8

DirectionID is a mechanism for distinguishing between trips going in the opposite direction. 

const (
	DirectionID_Unspecified DirectionID = 0
	DirectionID_True        DirectionID = 1
	DirectionID_False       DirectionID = 2
)

func (DirectionID) String 

func (d DirectionID) String() string

type ExactTimes added in v0.1.16 

type ExactTimes int32

ExactTimes describes the type of service for a trip.

This is a Go representation of the enum described in the `exact_times` field of `frequencies.txt`. 

const (
	FrequencyBased ExactTimes = 0
	ScheduleBased  ExactTimes = 1
)

func (ExactTimes) String added in v0.1.16 

func (t ExactTimes) String() string

type Frequency added in v0.1.16 

type Frequency struct {
	StartTime  time.Duration
	EndTime    time.Duration
	Headway    time.Duration
	ExactTimes ExactTimes
}

type OccupancyStatus added in v0.1.14 

type OccupancyStatus = gtfsrt.VehiclePosition_OccupancyStatus

type ParseRealtimeOptions 

type ParseRealtimeOptions struct {
	// The timezone to interpret date field.
	//
	// It can be nil, in which case UTC will used.
	Timezone *time.Location

	// The GTFS Realtime extension to use when parsing.
	//
	// This can be nil, in which case no extension is used.
	Extension extensions.Extension
}

type ParseStaticOptions 

type ParseStaticOptions struct {
	// If true, wheelchair boarding information is inherited from parent station
	// when unspecified for a child stop/platform, entrance, or exit.
	InheritWheelchairBoarding bool
}

type PickupDropOffPolicy added in v0.1.16 

type PickupDropOffPolicy int32

PickupDropOffPolicy describes the pickup or drop-off policy for a route or scheduled trip.

This is a Go representation of the enum described in the `continuous_pickup` field of `routes.txt`, and `pickup_type` field of `stop_times.txt`, and similar fields. 

const (
	// Pickup or drop off happens by default.
	PickupDropOffPolicy_Yes PickupDropOffPolicy = 0
	// No pickup or drop off is possible.
	PickupDropOffPolicy_No PickupDropOffPolicy = 1
	// Must phone an agency to arrange pickup or drop off.
	PickupDropOffPolicy_PhoneAgency PickupDropOffPolicy = 2
	// Must coordinate with a driver to arrange pickup or drop off.
	PickupDropOffPolicy_CoordinateWithDriver PickupDropOffPolicy = 3
)

func (PickupDropOffPolicy) String added in v0.1.16 

func (t PickupDropOffPolicy) String() string

type Position added in v0.1.14 

type Position struct {
	// Degrees North, in the WGS-84 coordinate system.
	Latitude *float32
	// Degrees East, in the WGS-84 coordinate system.
	Longitude *float32
	// Bearing, in degrees, clockwise from North, i.e., 0 is North and 90 is East.
	// This can be the compass bearing, or the direction towards the next stop
	// or intermediate location.
	// This should not be direction deduced from the sequence of previous
	// positions, which can be computed from previous data.
	Bearing *float32
	// Odometer value, in meters.
	Odometer *float64
	// Momentary speed measured by the vehicle, in meters per second.
	Speed *float32
}

type Realtime 

type Realtime struct {
	CreatedAt time.Time

	Trips []Trip

	Vehicles []Vehicle

	Alerts []Alert
}

Realtime contains the parsed content for a single GTFS realtime message.

func ParseRealtime 

func ParseRealtime(content []byte, opts *ParseRealtimeOptions) (*Realtime, error)

type Route 

type Route struct {
	Id                string
	Agency            *Agency
	Color             string
	TextColor         string
	ShortName         string
	LongName          string
	Description       string
	Type              RouteType
	Url               string
	SortOrder         *int32
	ContinuousPickup  PickupDropOffPolicy
	ContinuousDropOff PickupDropOffPolicy
}

Route corresponds to a single row in the routes.txt file.

type RouteType 

type RouteType int32

RouteType describes the type of a route.

This is a Go representation of the enum described in the `route_type` field of `routes.txt`. 

const (
	RouteType_Tram       RouteType = 0
	RouteType_Subway     RouteType = 1
	RouteType_Rail       RouteType = 2
	RouteType_Bus        RouteType = 3
	RouteType_Ferry      RouteType = 4
	RouteType_CableTram  RouteType = 5
	RouteType_AerialLift RouteType = 6
	RouteType_Funicular  RouteType = 7
	RouteType_TrolleyBus RouteType = 11
	RouteType_Monorail   RouteType = 12

	RouteType_Unknown RouteType = 10000
)

func (RouteType) String 

func (t RouteType) String() string

type ScheduledStopTime added in v0.1.5 

type ScheduledStopTime struct {
	Trip                  *ScheduledTrip
	Stop                  *Stop
	ArrivalTime           time.Duration
	DepartureTime         time.Duration
	StopSequence          int
	Headsign              string
	PickupType            PickupDropOffPolicy
	DropOffType           PickupDropOffPolicy
	ContinuousPickup      PickupDropOffPolicy
	ContinuousDropOff     PickupDropOffPolicy
	ShapeDistanceTraveled *float64
	ExactTimes            bool
}

type ScheduledTrip added in v0.1.5 

type ScheduledTrip struct {
	Route                *Route
	Service              *Service
	ID                   string
	Headsign             string
	ShortName            string
	DirectionId          DirectionID
	BlockID              string
	WheelchairAccessible WheelchairBoarding
	BikesAllowed         BikesAllowed
	StopTimes            []ScheduledStopTime
	Shape                *Shape
	Frequencies          []Frequency
}

type Service added in v0.1.5 

type Service struct {
	Id           string
	Monday       bool
	Tuesday      bool
	Wednesday    bool
	Thursday     bool
	Friday       bool
	Saturday     bool
	Sunday       bool
	StartDate    time.Time
	EndDate      time.Time
	AddedDates   []time.Time
	RemovedDates []time.Time
}

type Shape added in v0.1.16 

type Shape struct {
	ID     string
	Points []ShapePoint
}

type ShapePoint added in v0.1.16 

type ShapePoint struct {
	Latitude  float64
	Longitude float64
	Distance  *float64
}

type ShapeRow added in v0.1.16 

type ShapeRow struct {
	ShapePtLat        float64
	ShapePtLon        float64
	ShapePtSequence   int32
	ShapeDistTraveled *float64
}

type Static 

type Static struct {
	Agencies  []Agency
	Routes    []Route
	Stops     []Stop
	Transfers []Transfer
	Services  []Service
	Trips     []ScheduledTrip
	Shapes    []Shape

	// Warnings raised during GTFS static parsing.
	Warnings []warnings.StaticWarning
}

Static contains the parsed content for a single GTFS static message.

func ParseStatic 

func ParseStatic(content []byte, opts ParseStaticOptions) (*Static, error)

ParseStatic parses the content as a GTFS static feed.

type Stop added in v0.1.4 

type Stop struct {
	Id                 string
	Code               string
	Name               string
	Description        string
	ZoneId             string
	Longitude          *float64
	Latitude           *float64
	Url                string
	Type               StopType
	Parent             *Stop
	Timezone           string
	WheelchairBoarding WheelchairBoarding
	PlatformCode       string
}

func (*Stop) Root added in v0.1.4 

func (stop *Stop) Root() *Stop

Root returns the root stop.

type StopTimeEvent 

type StopTimeEvent struct {
	Time        *time.Time
	Delay       *time.Duration
	Uncertainty *int32
}

type StopTimeUpdate 

type StopTimeUpdate struct {
	StopSequence         *uint32
	StopID               *string
	Arrival              *StopTimeEvent
	Departure            *StopTimeEvent
	NyctTrack            *string
	ScheduleRelationship StopTimeUpdateScheduleRelationship
}

TODO: shouldn't this just be StopTime?

func (*StopTimeUpdate) GetArrival added in v0.1.1 

func (stopTimeUpdate *StopTimeUpdate) GetArrival() StopTimeEvent

func (*StopTimeUpdate) GetDeparture added in v0.1.1 

func (stopTimeUpdate *StopTimeUpdate) GetDeparture() StopTimeEvent

type StopTimeUpdateScheduleRelationship added in v0.1.23 

type StopTimeUpdateScheduleRelationship = gtfsrt.TripUpdate_StopTimeUpdate_ScheduleRelationship

type StopType added in v0.1.4 

type StopType int32

StopType describes the type of a stop.

This is a Go representation of the enum described in the `location_type` field of `stops.txt`. 

const (
	StopType_Stop           StopType = 0
	StopType_Station        StopType = 1
	StopType_EntranceOrExit StopType = 2
	StopType_GenericNode    StopType = 3
	StopType_BoardingArea   StopType = 4
	StopType_Platform       StopType = 5
)

func (StopType) String added in v0.1.4 

func (t StopType) String() string

type Transfer added in v0.1.4 

type Transfer struct {
	From            *Stop
	To              *Stop
	Type            TransferType
	MinTransferTime *int32
}

type TransferType added in v0.1.4 

type TransferType int32

StopType describes the type of a transfer.

This is a Go representation of the enum described in the `transfer_type` field of `transfers.txt`. 

const (
	TransferType_Recommended  TransferType = 0
	TransferType_Timed        TransferType = 1
	TransferType_RequiresTime TransferType = 2
	TransferType_NotPossible  TransferType = 3
)

func (TransferType) String added in v0.1.4 

func (t TransferType) String() string

type Trip 

type Trip struct {
	ID              TripID
	StopTimeUpdates []StopTimeUpdate

	Vehicle *Vehicle

	IsEntityInMessage bool
}

func (*Trip) GetVehicle added in v0.1.1 

func (trip *Trip) GetVehicle() Vehicle

func (*Trip) Hash added in v0.1.13 

func (t *Trip) Hash(h hash.Hash)

Hash calculates a hash of a trip using the provided hash function.

The Vehicle and IsEntityInFeed fields are ignored for the purposes of hashing.

type TripID 

type TripID struct {
	ID          string
	RouteID     string
	DirectionID DirectionID

	HasStartTime bool
	StartTime    time.Duration

	HasStartDate bool
	StartDate    time.Time

	ScheduleRelationship TripScheduleRelationship
}

func (TripID) Less added in v0.1.23 

func (t1 TripID) Less(t2 TripID) bool

Define ordering on trip ids for test consistency

type TripScheduleRelationship added in v0.1.23 

type TripScheduleRelationship = gtfsrt.TripDescriptor_ScheduleRelationship

type Vehicle 

type Vehicle struct {
	ID *VehicleID

	Trip *Trip

	Position *Position

	CurrentStopSequence *uint32

	StopID *string

	CurrentStatus *CurrentStatus

	Timestamp *time.Time

	CongestionLevel CongestionLevel

	OccupancyStatus *OccupancyStatus

	OccupancyPercentage *uint32

	IsEntityInMessage bool
}

func (*Vehicle) GetID added in v0.1.1 

func (vehicle *Vehicle) GetID() VehicleID

func (*Vehicle) GetTrip added in v0.1.1 

func (vehicle *Vehicle) GetTrip() Trip

func (*Vehicle) Hash added in v0.1.13 

func (v *Vehicle) Hash(h hash.Hash)

Hash calculates a hash of a vehicle using the provided hash function.

The Trip and IsEntityInFeed fields are ignored for the purposes of hashing.

type VehicleID 

type VehicleID struct {
	ID           string
	Label        string
	LicensePlate string
}

type WheelchairBoarding added in v0.1.4 

type WheelchairBoarding int32

WheelchairBoarding describes whether wheelchair boarding is available at a stop.

This is a Go representation of the enum described in the `wheelchair_boarding` field of `stops.txt` and `wheelchair_accessible` field of `trips.txt`. 

const (
	WheelchairBoarding_NotSpecified WheelchairBoarding = 0
	WheelchairBoarding_Possible     WheelchairBoarding = 1
	WheelchairBoarding_NotPossible  WheelchairBoarding = 2
)

func (WheelchairBoarding) String added in v0.1.6 

func (w WheelchairBoarding) String() string

Source Files

View all Source files

Directories

Path Synopsis
Package csv is a wrapper around the stdlib csv library that provides a nice API for the GTFS static parser.
 Package csv is a wrapper around the stdlib csv library that provides a nice API for the GTFS static parser.
nyctalerts
nycttrips
Package nycttrips contains logic for the New York City Transit GTFS realtime extensions
 Package nycttrips contains logic for the New York City Transit GTFS realtime extensions
internal
testutil
Package journal contains a tool for building trip journals.
 Package journal contains a tool for building trip journals.

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.