gtfs_gleam - v1.0.0

gtfs_gleam

Package Version Hex Docs

A comprehensive, type-safe GTFS (General Transit Feed Specification) library for Gleam, supporting both GTFS Static (schedule data) and GTFS Realtime (live updates).

Features

Installation

gleam add gtfs_gleam

Quick Start

Loading a GTFS Static Feed

import gtfs/static/feed

pub fn main() {
  // Load from a directory
  let assert Ok(feed) = feed.load_from_directory("./gtfs_data")
  
  // Or load from a ZIP file
  let assert Ok(feed) = feed.load_from_zip("./gtfs.zip")
  
  // Access the data
  io.println("Routes: " <> int.to_string(list.length(feed.routes)))
  io.println("Stops: " <> int.to_string(list.length(feed.stops)))
  
  // Query the feed
  let route = feed.get_route(feed, "route_1")
  let stop = feed.get_stop(feed, "stop_100")
}

Decoding GTFS Realtime

import gtfs/realtime/feed as rt_feed

pub fn handle_realtime(data: BitArray) {
  // Decode a protobuf feed
  let assert Ok(feed) = rt_feed.decode(data)
  
  // Get all trip updates
  let trip_updates = rt_feed.get_trip_updates(feed)
  
  // Get all vehicle positions  
  let vehicles = rt_feed.get_vehicle_positions(feed)
  
  // Get all alerts
  let alerts = rt_feed.get_alerts(feed)
  
  // Query specific data
  let delay = rt_feed.get_trip_delay(feed, "trip_123")
  let vehicle = rt_feed.get_vehicle_position(feed, "vehicle_456")
  let route_alerts = rt_feed.get_alerts_for_route(feed, "route_1")
}

Parsing Individual Files

import gtfs/static/files/agency
import gtfs/static/files/routes
import gtfs/static/files/stops

pub fn parse_files() {
  // Parse agency.txt
  let assert Ok(agencies) = agency.parse("./gtfs_data/agency.txt")
  
  // Parse routes.txt
  let assert Ok(routes) = routes.parse("./gtfs_data/routes.txt")
  
  // Parse stops.txt
  let assert Ok(stops) = stops.parse("./gtfs_data/stops.txt")
}

Geographic Utilities

import gtfs/common/geo

pub fn geo_example() {
  // Calculate distance between two points (in km)
  let distance = geo.distance_km(
    40.7128, -74.0060,  // New York
    34.0522, -118.2437  // Los Angeles
  )
  
  // Decode a polyline
  let points = geo.decode_polyline("_p~iF~ps|U_ulLnnqC_mqNvxq`@")
  
  // Check if point is in polygon
  let in_bounds = geo.point_in_polygon(lat, lon, polygon_points)
}

Feed Validation

import gtfs/static/validation as v

pub fn validate_feed(feed: Feed) {
  // Validate required files
  let context = v.ValidationContext(
    has_stops: True,
    has_locations_geojson: False,
    has_calendar: True,
    has_calendar_dates: True,
  )
  let file_errors = v.validate_required_files(context)
  
  // Validate foreign key relationships
  let route_errors = v.validate_route_refs(feed.trips, feed.routes)
  let stop_errors = v.validate_stop_refs(feed.stop_times, feed.stops)
  
  // Validate semantic rules
  let coord_errors = v.validate_stop_coordinates(feed.stops)
  let time_errors = v.validate_stop_time_sequences(feed.stop_times)
}

Module Structure

Static (Schedule Data)

Realtime (Live Updates)

Common

Supported GTFS Files

Core Files

Optional Files

Fares v2 Files

GTFS-Flex Files

GTFS Realtime Support

Full support for decoding GTFS Realtime Protocol Buffer feeds:

Development

gleam build   # Build the project
gleam test    # Run the tests
gleam docs build  # Generate documentation

License

MIT License - see LICENSE for details.

References

✨ Search Document