SignageHTML/docs/API_RESPONSE_DOCUMENTATION.md

SL Transport API Response Structure

Overview

The SL Transport API returns departure information for a specific stop/site. The response is a JSON object containing an array of departure objects.

Response Structure

{
  "departures": [
    {
      "destination": "T-Centralen",
      "direction_code": 2,
      "direction": "T-Centralen",
      "state": "EXPECTED",
      "display": "Nu",
      "scheduled": "2025-12-31T15:16:00",
      "expected": "2025-12-31T15:24:52",
      "journey": {
        "id": "...",
        "direction": "...",
        // other journey fields
      },
      "line": {
        "designation": "7",
        "transportMode": "TRAM",
        // other line fields
      }
      // potentially other fields
    }
  ]
}

Field Explanations

Top-Level Fields

Field	Type	Description	How We Use It
departures	Array	List of departure objects	We iterate through this array to display all departures

Departure Object Fields

Field	Type	Description	How We Use It
destination	String	Final destination name (e.g., "T-Centralen", "Djurgårdsbrunn")	Displayed as destination name on the board
direction_code	Number	Direction indicator: 1 = going TO that direction, 2 = going FROM that direction	Used to determine arrow direction (1 = left ←, 2 = right →)
direction	String	Direction text (usually same as destination)	Available but we use direction_code instead
state	String	Departure state: "EXPECTED", "ATSTOP", etc.	Not currently used, but could indicate if bus is at stop
display	String	Human-readable time display: "Nu", "1 min", "2 min", "5 min", or time like "15:23"	Used for countdown display - we also calculate from scheduled
scheduled	ISO DateTime String	Original scheduled departure time (e.g., "2025-12-31T15:16:00")	Used to calculate minutes until arrival and format time display
expected	ISO DateTime String	Expected/actual departure time (may differ from scheduled)	Available but we use scheduled for consistency
journey	Object	Journey information	We use journey.id to track unique departures
journey.id	String	Unique journey identifier	Used as unique key for tracking departures
line	Object	Line/route information	Contains line number and transport type
line.designation	String	Line number (e.g., "7", "69", "76")	Displayed as the bus/tram number
line.transportMode	String	Transport type: "BUS", "TRAM", "METRO", "TRAIN", "SHIP"	Used to determine icon and styling

Current Usage in Code

✅ Correctly Used Fields

1. destination - Displayed as destination name
2. direction_code - Used to determine arrow direction (1 = left, 2 = right)
3. display - Used for countdown text (but we also calculate from scheduled)
4. scheduled - Used to calculate minutes until arrival and determine color (red < 5 min, white >= 5 min)
5. journey.id - Used as unique identifier for tracking departures
6. line.designation - Displayed as line number
7. line.transportMode - Used to determine transport icon and label

⚠️ Available But Not Used

1. expected - Could be used instead of scheduled for more accurate times
2. state - Could be used to show special status (e.g., "ATSTOP" = bus is at stop now)
3. direction - Text version of direction (we use direction_code instead)

Recommendations

Current Implementation is Correct ✅

Your current implementation is using the right fields:

• scheduled is the correct field to use for time calculations (more reliable than expected)
• direction_code is the correct field for arrow direction
• display is good for showing the API's formatted time, but calculating from scheduled ensures consistency

Potential Enhancements

1. Use state field: Could highlight when state === "ATSTOP" to show bus is currently at the stop
2. Fallback to expected: If expected differs significantly from scheduled, could show both times
3. Use direction text: Could display alongside destination for clarity

Example API Response

{
  "departures": [
    {
      "destination": "T-Centralen",
      "direction_code": 2,
      "direction": "T-Centralen",
      "state": "EXPECTED",
      "display": "Nu",
      "scheduled": "2025-12-31T15:16:00",
      "expected": "2025-12-31T15:24:52",
      "journey": {
        "id": "some-unique-id"
      },
      "line": {
        "designation": "7",
        "transportMode": "TRAM"
      }
    },
    {
      "destination": "Djurgårdsbrunn",
      "direction_code": 1,
      "direction": "Djurgårdsbrunn",
      "state": "EXPECTED",
      "display": "1 min",
      "scheduled": "2025-12-31T15:28:38",
      "expected": "2025-12-31T15:29:00",
      "journey": {
        "id": "another-unique-id"
      },
      "line": {
        "designation": "69",
        "transportMode": "BUS"
      }
    }
  ]
}

Summary

You are using the correct data! The fields you're using (destination, direction_code, display, scheduled, line.designation, line.transportMode, journey.id) are the most important and reliable fields from the API response.