gtfs

package module
v0.1.20 Latest Latest
Warning

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

Go to latest
Published: Apr 26, 2024 License: MIT Imports: 16 Imported by: 2

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 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 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{}

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
}

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
}

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
}

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 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
	NyctIsAssigned  bool

	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
}

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

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.
nycttrips
Package nycttrips contains logic for the New York City Transit GTFS realtime extenstions
Package nycttrips contains logic for the New York City Transit GTFS realtime extenstions
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL