137 lines
5.3 KiB
Markdown
137 lines
5.3 KiB
Markdown
# 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.
|