Train Announcement API

Generate BSL train announcement videos using Signapse AI technology.

POST/v1/sign-requests/train-announcements

Rate limit: 1,500 requests per 5 minutes on both Staging and Production.

Authentication

All requests require an OAuth2 Bearer token in the Authorization header. See How to Authenticate for details.

Request Body

The request body is a JSON object with announcement parameters. Only destination is required — all other fields are optional and combine to form different announcement types.

Core Parameters

Core

Name	Type	Required	Description
destination	string	required	Destination of train. 3-letter CRS code or TIPLOC code. Default: `KGX`
timing	string	optional	Time of train departure. 4-digit HHMM format (e.g. "1130"). Empty string if no timing.
platform	string	optional	Platform number (0-24). Can include letters A-D (e.g. "3A"). Empty string if unknown.
operator	string	optional	ATOC code of UK Train Operating Company (e.g. "SW", "GR").
via	string	optional	Comma-separated CRS codes for intermediate stations (e.g. "SOU,BMH").

Delays, Cancellations & Updates

Updates

Name	Type	Required	Description
updatedTiming	string	optional	New departure time if delayed. 4-digit HHMM format.
updatedPlatform	string	optional	New platform if changed. Same format as platform.
cancelled	boolean	optional	Set to "true" if the train is cancelled. Default: `false`
shortDelay	boolean	optional	Set to "true" if the train is indefinitely delayed. Default: `false`
longDelay	boolean	optional	Set to "true" for indefinitely delayed with apology message. Default: `false`
disruptionReason	string	optional	Darwin disruption code for delay, cancellation, or not-calling-at reason.
noPlatform	boolean	optional	Set to "true" if no platform has been assigned yet. Default: `false`

Route Information

Route

Name	Type	Required	Description
callingAt	string	optional	Comma-separated CRS/TIPLOC codes for calling stations in order. Final destination is auto-added.
notCallingAt	string	optional	Comma-separated CRS codes for stations the train no longer stops at.
splitInfo	string	optional	Train splitting info. Format: "atXXX" (splits at), "splitXXX" (splits for), "frontXXX"/"backXXX" (front/back for), with optional carriage count (e.g. "atAWK,2frontWEY,3backSOU").

Display & Announcements

Display

Name	Type	Required	Description
platformInfo	string	optional	Alters message structure for platform announcements. nextapproachingnow
arrivalInfo	string	optional	Alters message structure for arrival announcements. will_arrivehas_arrived
stopInfo	string	optional	Alters message to "The next/final stop is...". nextfinal
currentlyAt	string	optional	CRS code of current station, or two comma-separated codes if between stations (e.g. "WAT,CLJ").
waitsHere	string	optional	Number of minutes the train waits at this station (e.g. "7").
exitSide	string	optional	Which side to exit the train. leftright

Service & Facility Status

Service

Name	Type	Required	Description
busReplacement	boolean	optional	Set to "true" if there is a replacement bus service. Default: `false`
currentStation	string	optional	CRS code of current station for bus replacement stop message. Requires busReplacement="true".
operatorDelay	string	optional	Operator-wide delay announcement. Must be paired with an "operator". minorseverespecial
liftStatus	string	optional	Lift status. Format: "Xbroke,Ywork", "allwork", or "allbroke" (e.g. "1broke,3work").
escalatorStatus	string	optional	Escalator status. Same format as liftStatus.
staticMessage	string	optional	Predefined static message code (e.g. "Wait", "British_Transport_Police"). Overrides all other request variables.
bgColour	string	optional	Background colour as comma-separated RGB values (e.g. "18,195,83"). Use "-1,-1,-1" for transparent .webm output.

Response

Returns a 200 OK with a request ID. Use this ID to poll for status.

data.idstring

The request/job ID. Use this to check the status of video generation.

Check Request Status

GET/v1/sign-requests/{requestId}

Poll this endpoint with the id from the generate response. Add ?filter=status to get a compact status response.

data.statusstring

Job status: IN_PROGRESS, COMPLETED, or FAILED.

data.downloadLinkstring

Presigned URL to download the generated video. Only present when status is COMPLETED.

data.errorLogstring

Error details. Only present when status is FAILED.

Error Codes

Status	Meaning
400	Request error — invalid parameters
401	Provided token cannot be verified
403	Token not provided or invalid token
404	Client not found

Common Use Cases

Basic Departure


{
  "destination": "KGX",
  "timing": "1130",
  "platform": "6"
}

Departure with Operator and Calling Points


{
  "destination": "NCL",
  "timing": "1458",
  "platform": "1",
  "operator": "GR",
  "callingAt": "DHM,DAR"
}

Cancellation with Reason


{
  "destination": "KGX",
  "timing": "1845",
  "cancelled": "true",
  "disruptionReason": "109"
}

Platform Change


{
  "destination": "SLB",
  "timing": "1422",
  "platform": "1",
  "updatedPlatform": "6"
}

Delay with Updated Time


{
  "destination": "BHI",
  "timing": "1010",
  "updatedTiming": "1030",
  "disruptionReason": "656"
}

Train Splitting


{
  "splitInfo": "atAWK,2frontWEY,3backSOU"
}

Transparent Background


{
  "destination": "LDS",
  "timing": "1220",
  "platform": "7",
  "bgColour": "-1,-1,-1"
}

Request

curl --location \
  'https://sign.client.api.stag.signapsesolutions.com/v1/sign-requests/train-announcements' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "destination": "KGX",
    "timing": "1130",
    "platform": "6",
    "operator": "GR",
    "callingAt": "DON,YRK"
  }'

Response

{
  "data": {
    "id": "c4c7ac45-79c2-48b2-99ff-61775e2d3d3e"
  }
}