API Overview
This API endpoint provides data regarding counters for assets in the Railnova platform, such as kilometers and engine hours. The data is presented in a flattened structure, making it easier to consume. The endpoint allows filtering and ordering, and results are paginated using LinkHeader pagination.
Endpoint URL:
https://{company}.railnova.eu/api/v2/counters/flattened.json
Method: GET
Authentication
Basic authentication with valid Railnova platform user credentials is required.
API Details
Response Example:
{
"id": 6947,
"asset_id": 12963,
"asset_name": "Flying Scotsman",
"asset_uic": null,
"asset_class_id": 260,
"asset_class_name": "A1",
"is_immobilised": false,
"telematic_source_message": "gps_km",
"telematic_source_column": "period_km",
"name": "gps_km",
"aggregate": "increment",
"value": "2241.0",
"unit": "km",
"daily_average_30d": "365.0",
"last_update": "2024-09-15T09:00:00+01:00",
"component_type_id": null,
"component_type_name": null,
"component_id": null,
"component_name": null,
"component_serial": null,
"data_freshness_first_threshold": "15",
"data_freshness_second_threshold": "60"
}
Field Descriptions
id: Unique identifier for the counter
asset_id: Unique identifier for the associated asset (e.g., locomotive, wagon)
asset_name: Name of the asset (e.g., "Flying Scotsman").
asset_uic: UIC number for the asset, if available.
asset_class_id: Unique identifier for the class of the asset (e.g., 260 for A1).
asset_class_name: Name of the asset's class (e.g., "A1").
is_immobilised: Boolean value indicating whether the asset is currently immobilized or not.
telematic_source_message: Telematic source message related to the counter data (e.g., "gps_km").
telematic_source_column: Telematic source column that stores the specific counter data (e.g., "period_km").
name: Name of the counter (e.g., "gps_km").
aggregate: Aggregation method used for the counter value (options are "increment" and "absolute")
value: Current value of the counter (e.g., "2241.0" km).
unit: Unit of measurement for the counter value (e.g., "km" for kilometers).
daily_average_30d: Average daily increment for the counter over the last 30 days.
last_update: Date and time when the counter was last updated (ISO 8601 format).
component_type_id: Identifier for the type of component related to the counter, if applicable
component_type_name: Name of the component type related to the counter, if applicable.
component_id: Identifier for the specific component related to the counter, if applicable
component_name: Name of the specific component related to the counter, if applicable.
component_serial: Serial number of the component related to the counter, if applicable.
data_freshness_first_threshold: First threshold value for determining data freshness (e.g., after 15 days, the data might be considered stale).
data_freshness_second_threshold: Second threshold value for data freshness (e.g., after 60 days, data may require intervention).
Query Parameters
The following query parameters are supported for filtering the data:
asset_id: Filter by asset ID.
asset_uic: Filter by UIC number of the asset.
asset_class_id: Filter by asset class ID.
asset_class_name: Filter by asset class name (e.g., "Flying Scotsman").
asset_name: Filter by asset name (e.g., "A1").
telematic_source_message: Filter by telematics source message (e.g., "gps_km").
telematic_source_column: Filter by telematics source column (e.g., "period_km").
aggregate: Filter by aggregation type (e.g., "increment").
name: Filter by the name of the counter.
last_update__gt: Return only results where last_update is greater than a specified date (format: YYYY-MM-DD).
last_update__lt: Return only results where last_update is less than a specified date (format: YYYY-MM-DD).
Example of a filtered request:
GET https://{company}.railnova.eu/api/v2/counters/flattened.json?asset_name=SKL429&last_update__gt=2022-01-01
Ordering
Results can be ordered using the ordering query parameter. The following values are supported:
name: Orders results by the counter name.
last_update_date: Orders results by the last update date.
daily_avg: Orders results by the daily average over the last 30 days.
counter_type__name: Orders results by counter type name.
asset__name: Orders results by asset name.
Example of an ordered request:
GET https://{company}.railnova.eu/api/v2/counters/flattened.json?ordering=last_update_dateOrdering can be reversed by adding "-" in front of the ordering value.
Example of an ordered request (reversed):
GET https://{company}.railnova.eu/api/v2/counters/flattened.json?ordering=-last_update_date
Pagination
The API uses LinkHeader pagination.
Error Codes
401 Unauthorized: Authentication failed. Check the username and password.
400 Bad Request: The request parameters are invalid.
404 Not Found: The resource requested could not be found.
Support
Do you still have questions? Go to the Railnova platform and click "Contact us" for help!
