njtapi

README

NJTAPI

NJTAPI is a Go library for accessing data about NJTransit Trains. It wraps the NJTransit HTTP API.

Features include:

• Timetables and statuses of departures from each station.
• Train status including location and stops.
• List of all the train stations in the system.

See the GoDoc for full details.

Installation

import "github.com/bamnet/njtapi"

API Access

Register with the NJTransit Developer Portal to get a username and password needed to call the API.

Example Usage

func main() {
	username := "your username"
	password := "your password"

	client := NewClient("http://njttraindata_tst.njtransit.com:8090/njttraindata.asmx/", username, password)
	station, err := client.StationData(context.Background(), "NY")
	if err != nil {
		log.Fatalf("StationData() error: %v", err)
	}
	fmt.Println("Departures from New York Penn Station")
	for _, departures := range station.Departures {
		fmt.Printf("Train to %s at %s", departures.Destination, departures.ScheduledDepartureDate)
	}
}

Demo

Run demo.go for a working demo using a command like:

go run demo/demo.go --base_url="http://njttraindata_tst.njtransit.com:8090/njttraindata.asmx/" --username=<USERNAME> --password=<PASSWORD>

Note: Both of the samples above point to a testing api server, not the production one.

Documentation

Overview

Package njtapi provides an library to access NJTransit Train data.

A valid username and password is required to call the NJTransit API. To register, head on over to https://datasource.njtransit.com/.

This library makes opinionated decisions about how data should be sanitized and modeled. As a result, it does not provide a 1:1 mapping of all of features and fields included in the API spec.

Index

• Variables
• type Client
  • func NewClient(baseURL, username, password string) *Client
  • func NewCustomClient(c *http.Client, baseURL, username, password string) *Client
  • func (c *Client) GetTrainMap(ctx context.Context, trainID int) (*Train, error)
  • func (c *Client) GetTrainStops(ctx context.Context, trainID int) (*Train, error)
  • func (c *Client) StationData(ctx context.Context, station string) (*Station, error)
  • func (c *Client) StationList(ctx context.Context) ([]Station, error)
  • func (c *Client) VehicleData(ctx context.Context) ([]Train, error)
• type LatLng
• type Line
• type Station
• type StationStop
• type StationTrain
• type Train

Examples

• Client.StationData

Variables

var (
	ErrTrainNotFound = errors.New("train not found")
)

Types

type Client

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

Client stores connection info needed talking to the NJTransit API.

func NewClient

func NewClient(baseURL, username, password string) *Client

NewClient constructs a new client to talk to the NJTransit API.

baseURL: The root URL that the API is exposed on. username / password: Authentication credentials for calling the API.

func NewCustomClient

func NewCustomClient(c *http.Client, baseURL, username, password string) *Client

NewCustomClient uses the supplied `http.Client` when talking to the API. This can be useful if you need to supply a custom timeout, proxy server, etc.

See `NewClient` for a description of the rest of the parameters.

func (*Client) GetTrainMap

func (c *Client) GetTrainMap(ctx context.Context, trainID int) (*Train, error)

Get information about a specific train from the "Map" API endpoint.

The `Train` object returned will not have all the fields set. It will typically only have `ID`, `Line`, `Direction`, `LastModified`, `LatLng`, and `TrackCircuit`.

func (*Client) GetTrainStops

func (c *Client) GetTrainStops(ctx context.Context, trainID int) (*Train, error)

Get information about a specific train from the "Stops" API endpoint.

The `Train` object returned will not have all the fields set. It will typically only have `ID`, `LastModified`, `LatLng`, and `Stops`.

func (*Client) StationData

func (c *Client) StationData(ctx context.Context, station string) (*Station, error)

StationData returns details about upcoming trains stopping at a station.

Example

func (*Client) StationList

func (c *Client) StationList(ctx context.Context) ([]Station, error)

StationList returns a list of all the stations available.

func (*Client) VehicleData

func (c *Client) VehicleData(ctx context.Context) ([]Train, error)

VehicleData returns up the most recent information about all "active" trains.

type LatLng

type LatLng struct {
	Lat float64 // Latitude
	Lng float64 // Longitude
}

LatLng models the latitude and longitude of an object.

type Line

type Line struct {
	Name string // Train line
}

A Line is train line, like the North Jersey Coast Line.

type Station

type Station struct {
	ID         string         // Station character code
	Name       string         // Station name
	Aliases    []string       // Additional names for this station
	Departures []StationTrain // Trains departing from this station
}

A Station provides information about the next trains stopping at a station.

type StationStop

type StationStop struct {
	Name          string    // Station stop name
	Time          time.Time // Estimated arrival time at this stop
	Departed      bool      // Indicates if the train has departed the stop or not
	DepartureTime time.Time // Time the train departed this station
	Lines         []Line    // Connecting lines available at this station
}

A StationStop is a stop this train will make, or has made, on it's route.

type StationTrain

type StationTrain struct {
	Index                  int           // Row index
	TrainID                int           // Train ID
	Line                   string        // Train line
	LineAbbrv              string        // Train line abbreviation
	Destination            string        // Destination for the train
	ScheduledDepartureDate time.Time     // Scheduled departure time from the station
	Track                  string        // Track number/letter
	Status                 string        // Current train status
	SecondsLate            time.Duration // Train delay
	LatLng                 *LatLng       // Train location
	LatLngTimestamp        time.Time     // Time the train location was measured
	InlineMsg              string        // In-line message for the train at this station
	Stops                  []StationStop // List of all stops for this train.
}

A StationTrain models a train which is scheduled to depart from a station.

type Train

type Train struct {
	ID                     int           // Train number
	Line                   string        // Train line
	Direction              string        // Eastbound or Westbound
	LastModified           time.Time     // ???
	ScheduledDepartureTime time.Time     // ???
	SecondsLate            time.Duration // Train delay
	NextStop               string        // Next station the train is stopping at, like "New York" or "Dover".
	LatLng                 *LatLng       // Last identified latlng
	TrackCircuit           string        // Track Circuit ID, like "CL-2WAK" or "BC-8251TK".
	Stops                  []StationStop // Stations the train stops at.
}

A Train summarizes the latest information about a train.