API Use-cases: Real-time passenger information applications and integrations

Ana Huie

Updated February 05, 2026 01:30

Overview

The Swiftly API provides multiple endpoints to access real-time transit data, each optimized for different use cases. Choosing the right endpoint architecture for your application ensures optimal performance, scalability, and efficient use of API resources.

This guide covers best practices for one of the most common use cases: displaying real-time arrival predictions for passenger-facing applications and integrations

Passenger Information Endpoints

Swiftly offers two main approaches for accessing prediction data:

1. GTFS-Realtime Trip Updates

Designed for system-wide data retrieval, high-volume systems
Best for: apps showing multiple predictions, trip planning, system monitoring
Example: "Show me all upcoming stops for this vehicle" or "Display predictions across my entire route network"

2. Predictions

Designed for targeted, low-volume specific queries
Best for: Single-stop displays, schedule boards, SMS notifications
Example: "When is the next bus arriving at Main Street?"

Choosing the right approach is critical. Using individual prediction endpoints when you need bulk data can lead to performance issues, rate-limits, and a poor user experience.

3. GTFS-Realtime Alerts

Designed for Real-time alert feeds, rider-facing applications, high-frequency polling
Best for: Mobile apps, digital signage, website alerts, notification systems
Examples: "Show active service disruptions affecting Route 15" or "Display all system-wide alerts on homepage"

Use-cases

[Predictions] Display Real-Time Predictions for Upcoming Stops in Your Transit Application

Use Case: You're building a passenger-facing application that needs to show the next several upcoming stops for a vehicle along with predicted arrival times.

Common Scenario: A rider boards a bus and your app displays the next 3-5 stops with countdowns like "Main Street - 2 minutes" or "City Hall - 5 minutes."

Recommended API: Use GTFS-Realtime Trip Updates

The most efficient way to retrieve prediction data for multiple stops is to use our GTFS-realtime (GTFS-rt) trip-updates feed as it:

Returns: a single API call returns predictions for all vehicles, routes, and stops
Updates every 5 seconds with fresh real-time data
Industry-standard format supported by many transit tools and libraries
Designed specifically for applications that need multiple predictions across your system
Dramatically reduces API calls and improves performance

Step 1: Access the GTFS-rt Trip Updates Feed

Endpoint format:

https://api.goswift.ly/real-time/{agency-id}/gtfs-rt-trip-updates

This returns a protobuf-encoded feed following the GTFS-realtime specification.

Step 2: Parse the Feed

Use a GTFS-realtime library for your backend language:

Python: gtfs-realtime-bindings
JavaScript/Node: gtfs-realtime-bindings (npm)
Java: gtfs-realtime-bindings (Maven)
Other languages: See GTFS.org language bindings

Step 3: Extract Relevant Data

The trip-updates feed contains:

Trip ID (identifies the vehicle's current trip)
Stop time updates for all stops on that trip
Predicted arrival and departure times
Stop sequence information

Step 4: Store and Serve Data

Cache the processed predictions in your backend (Redis, PostgreSQL, etc.) and expose them via your own API to your frontend application.

[Predictions] How to Display Next Arrival Times at a Specific Stop

This guide covers best practices for a common use case: displaying next arrival predictions at a single, specific stop location.

Scenario: You need to display when the next buses/trains will arrive at one specific stop location.

Common Examples:

Digital signage at a bus stop showing arriving buses
Website widget: "Next arrivals at Downtown Station"
Mobile app stop detail page showing upcoming vehicles

Recommended API: For single-stop queries, use the predictions endpoint to get targeted, real-time arrival information as it is:

Efficient for single-stop queries - Returns only the data you need
Flexible filtering - Query by stop, route, or both
Simple response format - Easy to parse and display
Low latency - Direct query without processing bulk feeds
Perfect for targeted use cases - When you know exactly which stop you need

Endpoint Format

GET https://api.goswift.ly/real-time/{agency-id}/predictions

Query Parameters

Parameter	Required	Description	Example
`stop`	Yes*	Stop ID to get predictions for	`stop=1234`
`route`	No	Filter to specific route	`route=15`
`number`	No	Route short name (alternative to route)	`number=15`
`verbose`	No	Include additional details	`verbose=true`

*Required: You must specify at least a stop parameter.

Example

Use case: "Show me the buses arriving at stop 5678, regardless of route"

bash

GET /real-time/swiftly/predictions?stop=5678

Response:

json

{
  "predictions": [
    {
      "route_id": "3",
      "route_short_name": "3",
      "route_long_name": "Burnet/Manchaca",
      "stop_id": "5678",
      "stop_name": "6th & Congress",
      "arrival_time": "2026-02-03T14:32:15Z",
      "arrival_seconds": 180,
      "vehicle_id": "1234"
    },
    {
      "route_id": "7",
      "route_short_name": "7",
      "route_long_name": "Duval/Dove Springs",
      "stop_id": "5678",
      "stop_name": "6th & Congress",
      "arrival_time": "2026-02-03T14:35:45Z",
      "arrival_seconds": 390,
      "vehicle_id": "5678"
    },
    {
      "route_id": "3",
      "route_short_name": "3",
      "route_long_name": "Burnet/Manchaca",
      "stop_id": "5678",
      "stop_name": "6th & Congress",
      "arrival_time": "2026-02-03T14:47:20Z",
      "arrival_seconds": 1085,
      "vehicle_id": "2345"
    }
  ]
}
```

**Display example:**
```
Next arrivals at 6th & Congress:
- Route 3 - 3 min
- Route 7 - 6 min  
- Route 3 - 18 min

Rate Limit Considerations

✅ Good patterns:

Query predictions when user navigates to a stop page
Refresh at reasonable intervals (20-30 seconds)
Cache responses briefly to handle rapid page reloads
One query per SMS/notification request

❌ Patterns to avoid:

Making 20+ prediction calls to show predictions at every stop on a route
- Solution: Use GTFS-realtime trip-updates feed instead
Querying predictions for stops not currently being viewed
Making parallel queries for dozens of stops simultaneously
Querying predictions for all stops in your system on a loop

[Alerts] Display Active Service Alerts in Your Transit Application

Use Case: You're building a rider-facing application that needs to show current service alerts, delays, detours, and disruptions.

Common Scenarios:

Mobile app showing alerts affecting user's routes
Website banner displaying system-wide service disruptions
Digital signage at stations showing current delays
Push notifications when alerts are created or updated
Trip planner showing alerts for selected routes

Recommended API: GTFS-Realtime Alerts

The most efficient way to retrieve current service alerts is to use our GTFS-realtime (GTFS-rt) service alerts feed.

Benefits

Only active alerts - Returns current and upcoming alerts, no historical data
No result limits - Get all active alerts in one call
Real-time updates - Reflects alert changes immediately
Industry standard - GTFS-realtime format supported by many transit tools
Efficient polling - Designed for frequent updates (every 30-60 seconds)
Rich metadata - Includes severity, affected entities, time ranges, descriptions

Step 1: Access the GTFS-rt Service Alerts Feed

Endpoint format:

GET https://api.goswift.ly/real-time/{agency-id}/gtfs-rt-alerts/v2

Authentication: Include your API key in the Authorization header:

curl --request GET \
  --url 'https://api.goswift.ly/real-time/{agency-id}/gtfs-rt-alerts/v2' \
  --header 'Authorization: {API_KEY}'

Step 2: Choose Your Format

The endpoint supports two response formats:

Protobuf (Recommended)

Default format - More efficient, smaller payload, standard GTFS-rt structure

curl --request GET \
  --url 'https://api.goswift.ly/real-time/{agency-id}/gtfs-rt-alerts/v2' \
  --header 'Authorization: {API_KEY}' \
  --header 'Accept: application/x-protobuf'

Benefits:

Smaller file size (faster downloads)
Complete field support
Standard GTFS-rt libraries handle parsing
Better for mobile apps with limited bandwidth

JSON (Alternative)

Human-readable format - Easier to debug, but slightly different field structure

bash

curl --request GET \
  --url 'https://api.goswift.ly/real-time/{agency-id}/gtfs-rt-alerts/v2?format=json' \
  --header 'Authorization: {API_KEY}' \
  --header 'Accept: application/json'

Note: JSON format may not include all fields available in protobuf. Use protobuf for production applications.

Step 3: Parse the Feed

For Protobuf (Recommended):

Use a GTFS-realtime library:

Python: gtfs-realtime-bindings
JavaScript/Node: gtfs-realtime-bindings (npm)
Java: gtfs-realtime-bindings (Maven)
Other languages: See GTFS.org language bindings

Step 4: Extract Alert Information

Each alert contains:

Basic Information:

Alert ID - Unique identifier
Header Text - Short alert summary (for headlines/titles)
Description Text - Detailed alert information
URL - Link to more information (optional)

Time Period:

Active Period - Start and end times for the alert
Can specify multiple active periods (e.g., weekdays only)

Affected Entities:

Routes - Which routes are affected
Stops - Which stops are affected
Trips - Specific trip instances affected
Can specify multiple entities per alert

Severity and Cause:

Effect - Type of disruption (delay, detour, no service, etc.)
Cause - Reason for alert (construction, weather, accident, etc.)

Rate Limits and Best Practices

GTFS-rt feeds: Designed to be polled frequently (~every 5 seconds). Standard API rate limits apply.
Individual prediction endpoints: Intended for specific, targeted queries, not bulk data retrieval.
Caching: Always cache GTFS-rt data in your backend for at least 30 seconds to reduce unnecessary API calls.
Graceful degradation: If fresh data isn't available, continue showing the last known predictions with a timestamp.

Additional Resources

Swiftly API Documentation - Full API reference
GTFS-Realtime Specification - Official GTFS-rt documentation
GTFS-Realtime Language Bindings - Parsing libraries

Need Help?

If you have questions about implementing GTFS-realtime feeds or need guidance on your specific use case, contact our Technical Support team at support@goswift.ly.

Last updated: February 2026