# 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

```json
{
  "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

```json
{
  "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.