Skip to main content
API Documentation: Counters

How to query the counters API, work with filtered and ordered data efficiently.

Updated over 3 months ago

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_date

Ordering 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!

Did this answer your question?