Refactor: Complete codebase reorganization and modernization
- Split server.js routes into modular files (server/routes/) - departures.js: Departure data endpoints - sites.js: Site search and nearby sites - config.js: Configuration endpoints - Reorganized file structure following Node.js best practices: - Moved sites-config.json to config/sites.json - Moved API_RESPONSE_DOCUMENTATION.md to docs/ - Moved raspberry-pi-setup.sh to scripts/ - Archived legacy files to archive/ directory - Updated all code references to new file locations - Added archive/ to .gitignore to exclude legacy files from repo - Updated README.md with new structure and organization - All functionality tested and working correctly Version: 1.2.0
This commit is contained in:
136
docs/API_RESPONSE_DOCUMENTATION.md
Normal file
136
docs/API_RESPONSE_DOCUMENTATION.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user