gtfs-to-pouch

Tools to query data from GTFS schedules using PouchDB databases.

Most of the functions follow a pattern where the function is called like

const agency = await getAgency(agencyDB)(id);

In this example, the call to getAgency(agencyDB) returns a function, which is then immediately called with the id parameter. The second function returns a promise, which resolves when the information is loaded from a database.

In general, databases are passed inside the first function, and ids are passed in the second.

Agency

function getAgency(
	db: PouchDB.Database<Agency>
): (agency_id?: string) => Promise<Agency>

Gets an agency from the schedule, or the first listed agency if no ID is used. Since most schedules have only 1 agency without an agency_id property, this function will return that agency.

Calendar Dates

function getCalendarDate(
	db: PouchDB.Database<CalendarDate>
): (service_id: string, date: string | moment.Moment) => Promise<CalendarDate>

Gets a specific calendar date object from the database

• date: Either a moment, or a string in the YYYYMMDD format.

function allExceptions(
	db: PouchDB.Database<CalendarDate>
): (service_id: string) => Promise<CalendarDate[]>

Returns every exception for the given service ID

function upcomingExceptions(
	db: PouchDB.Database<CalendarDate>
): (service_id: string, duration?: Duration, now?: Moment) => Promise<CalendarDate[]>

Returns exceptions for the following month, or a custom duration instead.

• duration: A moment duration, defaults to 1 month.
• now: The current time. Can be overriden.

Calendar

function calendarEntryToDays(cal: Calendar): Set<Weekdays>

Get the dates of service for a given calendar entry as a set of integers. 0 represents Sunday, 1 is Monday, etc.

function getDays(
	db: PouchDB.Database<Calendar>
): (service_id: string) => Promise<Set<Weekdays>>

Wraps calendarEntryToDays by looking up the calendar entry for a service ID

function dateRangeString(
	days: Set<Weekdays>,
	mode?: 'normal' | 'short' | 'min',
): string

Returns a string representing days of service, such as 'Daily' or 'Mon - Fri'

• days: Set of days in the week that are serviced by the route
• mode: Determins the format of the returned day names.
  • normal: Sunday, Monday, ...
  • short: Sun, Mon, ...
  • min: Su, Mo, ...

Routes

function getRouteName(route: Route): string

Returns the name string from the route. route_long_name is preferred, and route_short_name is used as a fallback

function getRoute(
	db: PouchDB.Database<Route>
): (route_id: string) => Promise<Route>

Get a route based on its route_id, which is different from the _id used in the database

function listRoutes(
	db: PouchDB.Database<Route>
): () => Promise<Route[]>

Get every single route

function connectedRoutes(
	stopTimesDB: PouchDB.Database<StopTime>,
	tripsDB: PouchDB.Database<Trip>,
	routesDB: PouchDB.Database<Route>,
): (stop_id: string) => Promise<Route[]>

Get every route that connects to a given stop

function routeDays(
	tripDB: PouchDB.Database<Trip>,
	calendarDB: PouchDB.Database<Calendar>,
): (route_id: string) => Promise<Set<Weekdays>>

Returns all days of the week that a route is active on

Shapes

function getShapePoint(
	db: PouchDB.Database<Shape>
): (shape_id: string, shape_pt_sequence: number) => Promise<Shape>

Returns a specific point in a shape

function getAllPoints(
	db: PouchDB.Database<Shape>
): (shape_id: string) => Promise<Shape[]>

Returns every point in a shape, sorted by their shape_pt_sequence

function shapeAsGeoJSON(shape: Shape[]): GeoJSON.Feature<GeoJSON.LineString>

Converts a series of shape point into a GeoJSON line string. The shape array should be sorted and all belong to the same shape_id

Stop Times

function getStopTime(
	db: PouchDB.Database<StopTime>
): (trip_id: string, stop_id: string, stop_sequence: number) => Promise<StopTime>

Gets a stop time from the database

function getTripSchedule(
	stopTimeDB: PouchDB.Database<StopTime>
): (trip_id: string) => Promise<StopTime[]>

Get the stop times associated with a trip, sorted by stop_sequence. Throws 404 error if no schedule is found.

function stopTimesForStop(
	stopTimeDB: PouchDB.Database<StopTime>
): (stop_id: string) => Promise<StopTime[]>

Returns stop times associated to a stop

function firstAndLastStop(
	db: PouchDB.Database<StopTime>
): (trip_id: string) => Promise<{ first_stop_id: string, last_stop_id: string }>

Returns the first and last stop in a trip's schedule. Throws if there is no schedule for the trip.

function nextStopFromList(
  stopTimes: StopTime[],
  now?: moment.Moment
): StopTime

Returns the next stop that will be reached based on a list of stop times. Throws if the list is empty.

function nextStopOfTrip(
	db: PouchDB.Database<StopTime>
): (trip_id: string, now?: moment.Moment) => Promise<StopTime>

function nextStopOfRoute(
	tripDB: PouchDB.Database<Trip>,
	stopTimeDB: PouchDB.Database<StopTime>,
): (route_id: string, now?: moment.Moment) => Promise<StopTime>

Stops

function getStop(
	db: PouchDB.Database<Stop>,
): (stop_id: string) => Promise<Stop>

Returns a stop from the database

function stopAddress(apiKey: string): (stop: Stop) => Promise<string>

Looks up the address for a stop using Google Reverse Geocoding

• apiKey: API key for Google API

function nearestStop(
	db: PouchDB.Database<Stop>,
): (pos: GeoJSON.Position) => Promise<Stop>
function nearestStop(
	db: PouchDB.Database<Stop>,
	maxDistance: number,
): (pos: GeoJSON.Position) => Promise<Stop|null>

Returns the nearest stop to some position. Optionally, a maximum distance from the position can be specified. Maximum distance is set in the same units as latitude and longitude.

function stopAsGeoJSON(stop: Stop): GeoJSON.Feature<GeoJSON.Point>

Returns the stop as a GeoJSON point.

interface LatLngBounds { southwest: GeoJSON.Position, northeast: GeoJSON.Position }
function allStopsAsGeoJSON(
	db: PouchDB.Database<Stop>,
): (bounds?: LatLngBounds) => Promise<GeoJSON.FeatureCollection<GeoJSON.Point>>

Returns every stop as a GeoJSON point. No properties are set on the resulting features, instead only the position and id are set. Internally, the stop id and position are indexed, so these points can be generated without loading the entire stop database.

• bounds: If set, the stops returned are limited to a certain area.

Trips

function getTrip(
	tripDB: PouchDB.Database<Trip>
): (trip_id: string, route_id?: string) => Promise<Trip>

Get a trip based on its trip_id, which is different from the _id used in the database. Providing a route_id will speed up the lookup.

function tripName(trip: Trip): string

Returns the name of the trip. Uses trip_short_name or trip_headsign, and returns an empty string if neither are avaliable

function allTripsForRoute(
	tripDB: PouchDB.Database<Trip>
): (route_id: string) => Promise<Trip[]>

Get every single trip that is a child of a route

function tripTimes(
	stopTimeDB: PouchDB.Database<StopTime>,
): (trip_id: string) => Promise<moment.Range>

Finds the earliest and latest time in the trip's schedule and returns an array representing a range. If the schedule is empty, null is returned instead.

function currentTrip(
	tripDB: PouchDB.Database<Trip>,
	stopTimeDB: PouchDB.Database<StopTime>,
): (route_id: string, now?: moment.Moment) => Promise<Trip>

Gets the trip that is currently running in a route. If none are running, the first trip is returned instead. If some are running, the earliest current trip is returned.

function siblingTrips(
	tripDB: PouchDB.Database<Trip>,
	stopTimeDB: PouchDB.Database<StopTime>,
): (trip: Trip) => Promise<{ previous: Trip|null, following: Trip|null }>

Gets the previous and following trips in this trip's route; that is, the trip that took place immediately before and immediately after.

GTFS object interfaces

Typescript interfaces are also exported under 'gtfs-to-pouch/dist/interfaces'.