The RailState API

The API at a glance

RailState exposes a single REST API, rooted at https://api.railstate.com/api/v3. Every route is a GET request, authenticated with the same bearer token, documented in one generated specification, and returns JSON.

The routes fall into two data families, distinguished by what you are trying to do, plus a small set of reference routes for sensor and region metadata. One token works for all of them.

Which one should I use?

Get your API token

The RailState API uses bearer token authentication. Every request must include an Authorization: Bearer <your-token> header. Tokens are tied to your account and inherit your account's data permissions. A single token works for every route, in both endpoint families.

Generate a token in the RailState UI

1. Sign in to RailState with your normal credentials.
2. Click the profile icon in the top-right to open the User account & settings menu, then choose Tokens.
3. Click Add new token.
4. On the Create token screen, enter a unique ID for this token (for example, "powerbi-ingestion" or "postman-testing").
   • The optional fields (Description, Not before date, Validity seconds — leave empty for a token that never expires — and Disabled, which defaults to off) are explained in the blue question-mark tooltips beside each field.
5. Press Submit to generate the token. Its value is shown once, right after you submit.
6. Copy the token immediately and store it in a password manager or secret store. You will not be able to view the token value again once you close the dialog.

Rotating or revoking a token

Treat tokens like passwords. Rotate them at least annually, after staff changes, or any time a token may have been exposed. To rotate: generate a new token first, switch your scripts and tools over to it, verify everything works, then disable the old one from the same Tokens page.

Store the token securely

Hard-coding the token in a script, or pasting it into a terminal command where it lands in your shell history, is the most common way tokens leak. Use your operating system's credential store and read it from an environment variable at runtime.

# 1) Save the token in Keychain (silent prompt, no shell-history exposure):
read -rs NEW_TOKEN
# Paste the token, press Enter
security add-generic-password -a "$USER" -s "RAILSTATE_API_TOKEN" -U -w "$NEW_TOKEN"
unset NEW_TOKEN

# 2) Add this to ~/.zprofile so every new shell exports the token:
cat >> ~/.zprofile <<'EOF'

# RailState API token sourced from macOS Keychain
export RAILSTATE_API_TOKEN="$(security find-generic-password -a "$USER" -s 'RAILSTATE_API_TOKEN' -w 2>/dev/null)"
EOF

# 3) Open a new Terminal window. macOS prompts once - click "Always Allow".
# 4) Verify it's loaded:
echo "${#RAILSTATE_API_TOKEN}"   # should print a number around 200-300

# With secret-tool (interactive prompt):
secret-tool store --label="RailState API" service railstate user "$USER"
# Paste the token at the prompt.

# Read it back in your shell rc (~/.profile or ~/.bashrc):
export RAILSTATE_API_TOKEN="$(secret-tool lookup service railstate user "$USER")"

# PowerShell — save once:
$token = Read-Host -AsSecureString "Paste RailState API token"
$plain = [Runtime.InteropServices.Marshal]::PtrToStringAuto(
  [Runtime.InteropServices.Marshal]::SecureStringToBSTR($token))
cmdkey /generic:RailState /user:$env:USERNAME /pass:$plain
Remove-Variable plain, token

# Read it back in a PowerShell profile or session:
$cred = Get-StoredCredential -Target RailState   # requires CredentialManager module
$env:RAILSTATE_API_TOKEN = $cred.GetNetworkCredential().Password

API basics & conventions

Two hard limits on how much you can ask for at once

• Search: 250 filter values per request. The cap counts every value across every filter, not per filter, so 250 car ids leaves no room for a sensor list. Exceeding it returns 400 "Search error: Too many search conditions were specified (N). The limit is set to 250."
• Any route: the URL must stay under roughly 4096 bytes. Long identifier lists hit this before you expect. 400 eight-digit ids is about 4000 bytes and works; 500 does not, returning 400 "An HTTP line is larger than 4096 bytes." Batch long lists rather than sending one enormous request.

A mistyped filter name returns unfiltered data

An unrecognized parameter name is ignored rather than rejected, so a typo returns 200 with results that were never filtered. An unrecognized value is properly rejected with a 400. Sanity-check the row count whenever you add a filter for the first time: if it does not change, the filter is not being applied.

Pagination: follow the link until it is empty

Responses come back in blocks. Each block carries a link to the next block; when that link is null, the data is complete. The two families use different field names, and Search has one extra behavior worth knowing:

• Sync routes return nextRequestLink. Follow it until it is absent. Once you have the link, drop your original query parameters — the link already carries the full query string.
• Search routes return nextPageUrl, and results are ordered by ascending detection time. Because a page is never split across sightings that share a detection time (all cars of one train sighting share one), a page can come back empty while nextPageUrl is still present. Do not stop on an empty results page; page until nextPageUrl is null. Starting with a larger limit (for example 1000) reduces empty pages, but it is not required: even with a small limit, the limit parameter is automatically increased in the nextPageUrl.

Query parameter encoding

• Text strings are not enclosed in quotes.
• Lists are comma-separated with no brackets and no spaces (for example car_type=Tank Car,Locomotive, URL-encoded).
• Composite values are JSON-encoded strings.
• URL-encode all special characters.
• Values are case-insensitive unless stated otherwise. The exceptions are region ids, region_route, and train_tag, which are case-sensitive.

Time format

Date and time parameters (such as detection_time_from) accept the ISO-8601 Instant format:

• UTC with Z suffix — 2026-05-09T00:00:00Z
• UTC offset — 2026-05-09T00:00:00-07:00
• Offset with IANA tag — 2026-05-09T00:00:00-06:00[America/Regina]
• Unix epoch seconds — 1746748800

Use an explicit offset (or named timezone) when you need a precise day boundary in a non-UTC zone, for example to match a "Monday in Pacific Time" report.

Retry pattern

Transient 5xx errors and connection resets do happen. Wrap calls in a retry loop with exponential backoff:

import time, requests

def get_with_retry(url, headers, params=None, max_retries=10):
    for attempt in range(max_retries):
        try:
            r = requests.get(url, headers=headers, params=params, timeout=60)
            r.raise_for_status()
            return r
        except requests.exceptions.HTTPError as e:
            code = getattr(e.response, "status_code", None)
            if code in (500, 502, 503, 504) and attempt < max_retries - 1:
                time.sleep(min(30 * (2 ** attempt), 300))
                continue
            raise
        except (requests.exceptions.ConnectionError,
                requests.exceptions.Timeout,
                requests.exceptions.ChunkedEncodingError):
            if attempt < max_retries - 1:
                time.sleep(min(15 * (2 ** attempt), 300))
            else:
                raise

Sync endpoints export & keep current

These routes return complete sighting records. The design intent is that you keep a local copy of RailState's data and patch it over time: do one initial full pull, then on each run fetch everything created or modified since your last run, and reconcile deletions. Everything here paginates with nextRequestLink.

Train data

Search endpoints targeted, filtered queries beta

Where the Sync family hands you whole records to filter yourself, the Search family does the filtering on RailState's side and returns only what matches. Two ideas make it powerful:

1. Field selection (projection). You list the groups of fields you want with the attributes parameter, and the response contains only those. This can shrink a payload by one to two orders of magnitude versus a full consist.
2. Server-side filtering. One parameter per condition: car type, direction, load status, reporting mark, container number, hazmat, route, owner, and more. Conditions combine with AND. Results come back already de-duplicated and ordered by ascending detection time.

The three routes

All three take the same parameters and the same filters. They differ only in what a “row” is, so pick the route that matches the unit you want to count.

Attributes: choose the fields you get back

attributes is required. It is a comma-separated list of data-element groups; the response populates only the groups you request. An attribute that does not apply to a route is rejected (for example CAR_POSITION on trains/search, or TRAIN_DIMENSIONS on cars/search).

The filter catalog

All filters are optional; combine any number and they apply together (AND). Each is a comma-separated list, and matching within a single filter is OR. Filters marked train also work on cars/containers search: a car matches if its train sighting matches.

Identifier & wildcard search

This is the capability the Sync family cannot offer: find equipment by its printed identity. Both car_id and container_id accept wildcards and are case-insensitive.

equipment_type_code (Umler, 4 chars: a letter then 3 digits, e.g. C113 or B###) uses # only. stenciled_shipping_spec additionally supports ? for any single letter and a trailing *. Both match only cars whose equipment id is recognized.

Route search

site_route encodes an ordered path across sensors, with a suffix that controls which sightings come back. This is how you express corridor volume, origin detection, and cycle-time queries server-side.

• #{id}{dir} — a detection at a specific sensor, direction one of N W S E or ? (any)
• ? — exactly one detection at any sensor
• * — any number of detections (including zero) at any sensors
• suffix ~F (full, default) returns all sightings between the first and last named sensor; ~E (end) returns only the last named sensor; ~S (start) returns only the first. Use ~E/~S for unique counting.

region_route is the same idea over regions instead of sensors (and is case-sensitive). tracking_mode decides whether a route condition must be satisfied by a whole train trip (Trains, default) or by an individual car/locomotive (Cars).

Result shaping & paging

Value reference

Worked examples

All manifest and petroleum-unit trains in Alberta over a window that carried at least one hazmat:

GET /api/v3/trains/search
  ?detection_time_from=2026-06-20T00:00:00Z
  &detection_time_to=2026-06-25T12:00:00Z
  &train_type=manifest,petroleum%20unit
  &hazmat_un=any
  &region=CA%2FAB@geo_states
  &limit=100
  &attributes=train_sighting_id,detection,rail_car,car_hazmats

Tank cars carrying UN1202 or UN1203 that crossed from the US into Canada (car-tracking, return the Canadian sighting):

GET /api/v3/cars/search
  ?tracking_mode=cars
  &detection_time_from=2026-06-20T00:00:00Z
  &detection_time_to=2026-06-25T12:00:00Z
  &car_type=tank%20car
  &hazmat_un=un1202,un1203
  &region_route=%2A%3CUS%3E%3CCA%23F%3E%2A@geo_countries~E
  &limit=500
  &attributes=train_sighting_id,detection,rail_car,car_hazmats

Containers at five sensors, de-duplicated to the last sighting per trip:

GET /api/v3/containers/search
  ?sightings_filter=last%20sightings
  &detection_time_from=2026-06-20T00:00:00Z
  &detection_time_to=2026-06-25T12:00:00Z
  &sensor=8,315,24,15,39
  &limit=500
  &attributes=train_sighting_id,detection,rail_car,container_params

Latest position of every train across a corridor — give a list of sensors and collapse each train trip to its single most recent sighting among them. A train seen at four of the sensors returns one row, the newest; widen or narrow the corridor by editing the sensor list:

GET /api/v3/trains/search
  ?sensor=500,496,494,392,420,422
  &detection_time_from=2026-07-05T00:00:00Z
  &detection_time_to=2026-07-09T00:00:00Z
  &sightings_filter=last%20sightings
  &attributes=train_sighting_id,detection,train_sighting_params

One row per train trip (trainTripId). “Last” is the most recent sighting among the sensors you list, within the time window — so the date range bounds it: a historical window gives each train's last position as of the window's end, while ending the window at the current time (or omitting detection_time_to) gives positions as of now. A trip that ran twice in the window returns each run's last sighting.

Keep a fleet current: fetch only what is new

A common pattern is tracking a fixed list of cars or containers and, on a schedule, pulling only what has moved since last time — instead of re-pulling the whole fleet on every call. The mechanism is a single timestamp: the moment of your last poll.

1. Hold one record per identifier locally — each car or container and its latest sighting.
2. On each poll, send your list with detection_time_from set to the time of your previous call. Send up to 250 identifiers per request and page larger fleets in batches.
3. Merge the response into your store, keeping the newest sighting per carId (or container ID). This is the same group-by-newest step described under De-duplication.

Everything you already hold is older than your last poll, so any row that comes back is genuinely new for that identifier. Cars with no activity since the last call are simply absent from the response — a quiet interval returns little or nothing, and you never receive a record you already have. Set the next poll's detection_time_from to the time of this call and repeat.

GET /api/v3/cars/search
  ?car_id=CN003846,UP512340,TILX290117    (your fleet — up to 250 per call)
  &detection_time_from=2026-07-08T12:00:00Z    (the time of your last poll)
  &limit=1000
  &attributes=car_sighting_id,detection,rail_car,sensor_local_times

The same call works on /containers/search with container_id. Add sightings_filter=last%20sightings to return one row per train trip when a tracked unit was seen by several sensors in the interval.

Reference endpoints sensors & regions

These routes return the metadata behind the sighting data: the sensor sites themselves, their uptime, and the region hierarchy. They take no time range and change slowly, so fetch them once and cache, then refresh occasionally. Use them to translate sensor IDs into names and timezones, and to build the region ids the Search family accepts.

De-duplication

Field & join reference

A Sync sighting is nested JSON, not a set of joinable tables: cars hang off the sighting and containers hang off their car. There are no foreign-key fields on the child objects. A car has no sightingId and no position field — its position in the train is its index in the cars array, and the containers riding on it are simply the objects in that car's containers array.

{ "sightings": [ {
    "sightingId": 2277993, "trainId": 1098616, "sensorId": 270,
    "detectionTimeUTC": ..., "lastModified": ...,
    "cars": [                       <-- array order IS train order
      { "type": "Locomotive", "carId": "CN  008873",
        "containers": [             <-- nested under the car, not a sibling table
          { "containerSightingId": ..., "identificationNumber": "TCLU123456",
            "position": "Bottom" } ] } ] } ] }

The keys that matter, and what each family calls them:

carId is null when the mark could not be read. Never group by carId without excluding nulls, or every unreadable car collapses into one phantom car. The container equivalent is incompleteId: true.

Flattening it into tables

To land this in a warehouse you invent the join keys as you flatten: copy the parent's sightingId onto each car row and stamp the array index as the car's position. Those columns are yours, not the API's.

# one row per car, with the keys a relational model needs
for s in response["sightings"]:
    for i, car in enumerate(s["cars"], start=1):        # 1-based, to match Search
        rows.append({
            "sightingId":   s["sightingId"],            # copied down from the parent
            "carPosition":  i,                          # the array index, not an API field
            "carType":      car["type"],
            "carId":        car.get("carId"),
            "lastModified": s.get("lastModified"),
        })
        for ct in car.get("containers") or []:
            container_rows.append({
                "sightingId":  s["sightingId"],
                "carPosition": i,                       # links the container to its car
                "containerId": ct.get("identificationNumber"),
                "stackSlot":   ct.get("position"),
            })

Once those columns exist, the usual joins work — but note they are joining your schema, not the API's:

SELECT c.carId, c.carType, ct.containerId, ct.stackSlot
FROM cars c
JOIN containers ct
  ON c.sightingId  = ct.sightingId
 AND c.carPosition = ct.carPosition

Make your first call

The fastest test is to fetch your list of sensors. It is small, fast, requires no parameters, and confirms your token is valid.

Path A — Excel (Power Query)

1. Open Excel and choose Data → Get Data → From Other Sources → From Web, then pick Advanced.
2. In URL parts, enter https://api.railstate.com/api/v3/sensors/overview.
3. Under HTTP request header parameters, add Name Authorization and Value Bearer YOUR_TOKEN_HERE.
4. Click OK, expand the sensors column into rows, then Close & Load.

Path B — Postman

1. New request: GET https://api.railstate.com/api/v3/sensors/overview.
2. On the Authorization tab set type Bearer Token and paste your token.
3. Click Send. Expect a 200 with a body that begins { "sensors": [ ... ] }.

Insomnia, Bruno, and Hoppscotch follow the same pattern.

Path C — Code (Python, R, Node, Go)

import os, requests

TOKEN = os.environ["RAILSTATE_API_TOKEN"]
headers = {"Authorization": f"Bearer {TOKEN}"}

r = requests.get(
    "https://api.railstate.com/api/v3/sensors/overview",
    headers=headers, timeout=60)
r.raise_for_status()
print(f"{len(r.json()['sensors'])} sensors")

curl one-liner to sanity-check a token:

curl -H "Authorization: Bearer $RAILSTATE_API_TOKEN" \
     https://api.railstate.com/api/v3/sensors/overview | head -c 400

Path D — BI tools

Power BI: use Get Data → Web (Advanced) with an Authorization header, exactly like the Excel steps. Tableau and Looker Studio do not support custom auth headers natively; the stable pattern is a small scheduled script that lands the data in a file or warehouse table, then point the BI tool at that.

Worked recipes

Recipe 1 — Incremental sync into your own database Sync

1. Persist the highest lastModified value you have ever seen.
2. Call full_sightings?last_modification_time_from=<that value> and page until nextRequestLink is empty. This catches new and updated sightings.
3. De-duplicate the batch by sightingId, newest lastModified wins (see De-duplication).
4. Upsert: replace each sighting and its child cars/containers wholesale.
5. Call deleted_sightings for the same window and purge those IDs.
6. Save the new high-water mark.

# De-dup the batch by sightingId, newest wins:
seen = {}
for s in sightings_batch:
    sid = str(s["sightingId"])
    if sid not in seen or (s.get("lastModified") or "") > (seen[sid].get("lastModified") or ""):
        seen[sid] = s
sightings_batch = list(seen.values())

Recipe 2 — Single-sensor daily traffic, by car type Search

No local filtering, one call per cut:

import os, requests
h = {"Authorization": f"Bearer {os.environ['RAILSTATE_API_TOKEN']}"}
params = {
    "sensor": "35",
    "detection_time_from": "2026-06-10T00:00:00Z",
    "detection_time_to":   "2026-06-11T00:00:00Z",
    "car_type": "Tank Car",
    "attributes": "car_sighting_id",
    "limit": 1000,
}
rows, url = [], "https://api.railstate.com/api/v3/cars/search"
while url:
    b = requests.get(url, headers=h, params=params, timeout=90).json()
    rows += b.get("results", [])
    url, params = b.get("nextPageUrl"), None   # never stop on an empty page
print(len(rows), "tank-car sightings")

Recipe 3 — Trace one car across the network Search

Find every sighting of a reporting mark over a quarter, in one query:

params = {
    "car_id": "CN  003846",         # spacing/case/leading-zeros are normalized
    "tracking_mode": "Cars",
    "sightings_filter": "All sightings",
    "detection_time_from": "2026-04-01T00:00:00Z",
    "detection_time_to":   "2026-07-01T00:00:00Z",
    "attributes": "car_sighting_id,detection,rail_car",
    "limit": 1000,
}
# page cars/search as in Recipe 2, then sort by detection.detectionTime

Recipe 4 — Corridor volume on a sensor pair Search

Trains that ran sensor 35 then sensor 49, counted once each (~E suffix):

params = {
    "site_route": "*#35?*#49?*~E",
    "tracking_mode": "Trains",
    "detection_time_from": "2026-06-08T00:00:00Z",
    "detection_time_to":   "2026-06-15T00:00:00Z",
    "attributes": "train_sighting_id,train_composition",
    "limit": 1000,
}
# page trains/search; sum trainComposition.carCount.cars for segment weight

Tips & gotchas

Other documentation

This page is the practical guide: how to authenticate, which family of endpoints to use, and worked examples. Two other references sit alongside it.

The generated endpoint specification

Every route, every query parameter, and every response data model is published in a specification generated from the API code itself, so it never drifts from what the API actually does. Reach for it when you need the exact type of a parameter or the complete field list of a response model. Two ways to open it:

• In any browser, no token required: api.railstate.com/api/v3/documentation
• Inside RailState: click the profile icon in the top-right, then Api documentation.

A third address, https://api.railstate.com/api/v3/documentation/html, serves identical content but requires the Authorization: Bearer header. Use it only if you are already sending that header.

The Data Dictionary

Field-level definitions for everything the API returns, including whether each field is available in the API, the UI, or both. Read it in the Knowledge Base: RailState Data Dictionary.

Getting help & feedback

• Knowledge Base: support.railstate.com — release notes, data dictionary, dashboard guides
• API help & Search beta feedback: support+API@railstate.com for tokens, integration questions, and anything about the API. Search is under active development, so tell us what worked, what was missing, and what you would change (or reply to the release announcement).
• UI and account questions: support+UI@railstate.com

When emailing about an API problem, include: the full URL you called, the timestamp, the HTTP status code and response body, and the email address tied to the token (never paste the token itself).