Creating Custom Transit Reminders Using the /records Endpoint

This guide explains how to use the Smartblitzmerker Open Data API to create personalized public transport reminders. We’ll demonstrate how to fetch upcoming departures from a specific station using query parameters like where, refine, and order_by, and automate alerts using tools such as cron or Node-RED.

Overview

The /records endpoint allows you to query real-time or scheduled transport data from SNCF datasets. By filtering for a specific station and ordering results by time, you can identify the next available departure and trigger a notification system.

Endpoint Reference

GET /datasets/{dataset_id}/records

Required: - dataset_id (e.g., bus-timetables, train-departures)

Common Parameters: - where: ODSQL condition to filter records (e.g., where=stop_name="Gare de Lyon") - refine: Faceted filter (e.g., refine=line_id:72) - order_by: Sorting key, such as order_by=departure_time asc - limit: Number of results to return - timezone: Adjust time to your local zone (e.g., timezone=Europe/Paris)

Example Query

To fetch the next departures from Gare de Lyon, ordered by time:

curl -G "https://ressources.data.sncf.com/api/explore/v2.1/catalog/datasets/train-departures/records" \
  --data-urlencode 'where=stop_name="Gare de Lyon"' \
  --data-urlencode 'order_by=departure_time asc' \
  --data-urlencode 'limit=5' \
  --data-urlencode 'timezone=Europe/Paris'

This request returns the next 5 scheduled departures from Gare de Lyon.

Automating Alerts

You can automate this process to run periodically and trigger a notification (e.g., a desktop pop-up, SMS, or smart speaker output).

Option 1: Using `cron` + `curl` + `notify-send` (Linux)

  1. Create a shell script (check_departure.sh):

#!/bin/bash
response=$(curl -sG "https://ressources.data.sncf.com/api/explore/v2.1/catalog/datasets/train-departures/records" \
  --data-urlencode 'where=stop_name="Gare de Lyon"' \
  --data-urlencode 'order_by=departure_time asc' \
  --data-urlencode 'limit=1' \
  --data-urlencode 'timezone=Europe/Paris')

departure=$(echo "$response" | jq -r '.results[0].departure_time')
notify-send "Next Departure from Gare de Lyon" "$departure"

  1. Add to crontab:

*/5 * * * * /path/to/check_departure.sh

This will check every 5 minutes and display a desktop notification.

Option 2: Using Node-RED

  1. Use an HTTP Request node to query the API.

  2. Use a JSON node to parse the response.

  3. Add a Function node to extract and format the departure time.

  4. Connect to a notification output (e.g., email, Telegram bot, mobile push).

This setup offers a visual drag-and-drop approach to automate and route transit alerts.

Advanced: Filter by Upcoming Departures (Next 10 Minutes)

To only fetch departures within the next 10 minutes, you can use a dynamic where clause with datetime comparison (server-side datetime functions are limited in the API, so apply this filtering locally if needed).

  1. Fetch the earliest upcoming departure from a given stop.

  2. Compare the result timestamp against the current time +10 minutes.

  3. Trigger the alert only if within the time window.

import requests
from datetime import datetime, timedelta
import pytz

now = datetime.now(pytz.timezone("Europe/Paris"))
future = now + timedelta(minutes=10)

r = requests.get(
    "https://ressources.data.sncf.com/api/explore/v2.1/catalog/datasets/train-departures/records",
    params={
        "where": 'stop_name="Gare de Lyon"',
        "order_by": "departure_time asc",
        "limit": 1,
        "timezone": "Europe/Paris"
    }
)
result = r.json()["results"][0]
departure_time = datetime.fromisoformat(result["departure_time"])

if now < departure_time < future:
    print(f"Upcoming train at {departure_time.strftime('%H:%M')}")
else:
    print("No departure in next 10 minutes")

Conclusion

The Smartblitzmerker API enables powerful transit tracking features with just a few well-placed queries. Combined with automation tools, this makes it easy to create a custom commuter assistant tailored to your schedule.