openapi: 3.1.0
info:
    title: 'Railigent X - Asset Feature API'
    description: "# Introduction\n\nThe **Railigent X - Asset Feature API** allows to retrieve real-time information about assets of eligible fleets.\nRailigent X uses cloud technology to normalize asset information across multiple fleets of assets to provide a unified access interface. \n\nThe API provides two categories of endpoints:\n* Fleets endpoints for discovering available assets of eligible fleets\n* Assets endpoints for retrieving information for specific assets or all assets of a specific fleet\n\n---\n\n# Service Usage Guide\n\nFor typical use cases, the usage of the **Railigent X - Asset Feature API** can be characterized as three-step workflow:\n\n<img src=\"static/usage_flow.png\" alt=\"Intended API usage flow.\" width=\"600\"/>\n\n1. Initially, you can use the ***Fleets*** endpoints to discover which fleets are available and which assets are eligible for each fleet.\n2. Based on the API response, you can determine which eligible assets are relevant for your individual use cases.\n3. For these assets, you can continuously retrieve live information using the ***Assets*** endpoints.\n\n---\n\n# Service Access Control\n\nOnly authenticated and authorized access to the API is allowed.\nYou can use your Railigent X credentials you have received from the Railigent X Support Desk.\n\n---\n\n# Service Usage Limits\n\nDepending on your individual API subscription, service usage limits (maximum number of requests per minute and maximum number of requests per hour) may apply.\nWhen reaching a service usage limit, all subsequent requests will yield a HTTP status code of ```429``` until the service usage limit is automatically reset.\n\n---\n\n# Service Changelog\n\nAPI versioning is based on the Semantic Versioning 2.0.0.\n\n## Version 1.0.0: \n  * Initial Release\n  * Compliance with Xcelerator REST API Guidelines V2\n"
    termsOfService: 'https://www.mobility.siemens.com/global/en/general/terms-of-use.html'
    contact:
        name: 'Railigent X Support Desk'
        url: 'https://www.railigent.com/'
        email: secure-operations.mobility@siemens.com
    version: v1
paths:
    '/v1/fleets/{fleetId}/assets':
        get:
            tags:
                - Assets
            summary: 'Retrieve information for all assets of a specific fleet.'
            description: "Retrieve information for all assets of a specific fleet.\n    Access to assets depends on the permission scope of your **Railigent X** credentials."
            operationId: list_all_assets_v1_fleets__fleetId__assets_get
            parameters:
                -
                    name: fleetId
                    in: path
                    required: true
                    schema: {type: string, minLength: 1, description: 'Unique identifier of an eligible fleet.', title: Fleetid}
                    description: 'Unique identifier of an eligible fleet.'
                -
                    name: fields
                    in: query
                    required: false
                    schema: {type: string, description: 'Optional filter expression for limiting the output to relevant features only. Use an empty string to explicitly retrieve all features of an asset or a comma-separated list of path specifications to select individual features.', examples: [features.gps, features.mileage, features.speed, features.trip, features.uic], default: "", title: Fields}
                    description: 'Optional filter expression for limiting the output to relevant features only. Use an empty string to explicitly retrieve all features of an asset or a comma-separated list of path specifications to select individual features.'
            responses:
                '200':
                    description: 'Successful Response'
                    content: {application/json: {schema: {anyOf: [{$ref: '#/components/schemas/AssetCollectionResponse'}, {$ref: '#/components/schemas/XceleratorErrorResponse'}], title: 'Response List All Assets V1 Fleets  Fleetid  Assets Get'}}}
                '400':
                    content: {application/json: {schema: {$ref: '#/components/schemas/XceleratorErrorResponse'}}}
                    description: 'Bad Request'
                '404':
                    content: {application/json: {schema: {$ref: '#/components/schemas/XceleratorErrorResponse'}}}
                    description: 'Not Found'
                '422':
                    description: 'Validation Error'
                    content: {application/json: {schema: {$ref: '#/components/schemas/HTTPValidationError'}}}
                '429':
                    content: {application/json: {schema: {$ref: '#/components/schemas/XceleratorErrorResponse'}}}
                    description: 'Too Many Requests'
    '/v1/fleets/{fleetId}/assets/{assetId}':
        get:
            tags:
                - Assets
            summary: 'Retrieve information for a specific asset of a specific fleet.'
            description: "Retrieve information for all assets of a specific fleet.\n    Access to an asset depends on the permission scope of your **Railigent X** credentials."
            operationId: get_asset_v1_fleets__fleetId__assets__assetId__get
            parameters:
                -
                    name: fleetId
                    in: path
                    required: true
                    schema: {type: string, minLength: 1, description: 'Unique identifier of an eligible fleet.', title: Fleetid}
                    description: 'Unique identifier of an eligible fleet.'
                -
                    name: assetId
                    in: path
                    required: true
                    schema: {type: string, minLength: 1, description: 'Unique identifier of an available asset.', title: Assetid}
                    description: 'Unique identifier of an available asset.'
                -
                    name: fields
                    in: query
                    required: false
                    schema: {type: string, description: 'Optional filter expression for limiting the output to relevant features only. Use an empty string to explicitly retrieve all features of an asset or a comma-separated list of path specifications to select individual features.', examples: [features.gps, features.mileage, features.speed, features.trip, features.uic], default: "", title: Fields}
                    description: 'Optional filter expression for limiting the output to relevant features only. Use an empty string to explicitly retrieve all features of an asset or a comma-separated list of path specifications to select individual features.'
            responses:
                '200':
                    description: 'Successful Response'
                    content: {application/json: {schema: {anyOf: [{$ref: '#/components/schemas/AssetResponse'}, {$ref: '#/components/schemas/XceleratorErrorResponse'}], title: 'Response Get Asset V1 Fleets  Fleetid  Assets  Assetid  Get'}}}
                '400':
                    content: {application/json: {schema: {$ref: '#/components/schemas/XceleratorErrorResponse'}}}
                    description: 'Bad Request'
                '404':
                    content: {application/json: {schema: {$ref: '#/components/schemas/XceleratorErrorResponse'}}}
                    description: 'Not Found'
                '422':
                    description: 'Validation Error'
                    content: {application/json: {schema: {$ref: '#/components/schemas/HTTPValidationError'}}}
                '429':
                    content: {application/json: {schema: {$ref: '#/components/schemas/XceleratorErrorResponse'}}}
                    description: 'Too Many Requests'
    /v1/fleets:
        get:
            tags:
                - Fleets
            summary: 'Retrieve information about all eligible fleets of assets.'
            description: "Retrieve information about all available fleets of assets. \n    Access to fleets depends on the permission scope of your **Railigent X** credentials. \n    You can use the information about eligible assets of each fleet returned by this endpoint to retrieve asset information via the **Assets** endpoints."
            operationId: list_fleets_v1_fleets_get
            responses:
                '200':
                    description: 'Successful Response'
                    content: {application/json: {schema: {anyOf: [{$ref: '#/components/schemas/FleetCollectionResponse'}, {$ref: '#/components/schemas/XceleratorErrorResponse'}], title: 'Response List Fleets V1 Fleets Get'}}}
                '400':
                    description: 'Bad Request'
                    content: {application/json: {schema: {$ref: '#/components/schemas/XceleratorErrorResponse'}}}
                '404':
                    description: 'Not Found'
                    content: {application/json: {schema: {$ref: '#/components/schemas/XceleratorErrorResponse'}}}
                '429':
                    description: 'Too Many Requests'
                    content: {application/json: {schema: {$ref: '#/components/schemas/XceleratorErrorResponse'}}}
    '/v1/fleets/{fleetId}':
        get:
            tags:
                - Fleets
            summary: 'Retrieve information about a specific eligible fleet of assets.'
            description: "Retrieve information about a specific eligible fleet of assets. \n    Access to a fleet depends on the permission scope of your **Railigent X** credentials.\n    You can use the information about eligible assets of a fleet returned by this endpoint to retrieve asset information via the **Assets** endpoints."
            operationId: get_fleet_v1_fleets__fleetId__get
            parameters:
                -
                    name: fleetId
                    in: path
                    required: true
                    schema: {type: string, minLength: 1, description: 'Unique identifier of an eligible fleet.', title: Fleetid}
                    description: 'Unique identifier of an eligible fleet.'
            responses:
                '200':
                    description: 'Successful Response'
                    content: {application/json: {schema: {anyOf: [{$ref: '#/components/schemas/FleetResponse'}, {$ref: '#/components/schemas/XceleratorErrorResponse'}], title: 'Response Get Fleet V1 Fleets  Fleetid  Get'}}}
                '400':
                    content: {application/json: {schema: {$ref: '#/components/schemas/XceleratorErrorResponse'}}}
                    description: 'Bad Request'
                '404':
                    content: {application/json: {schema: {$ref: '#/components/schemas/XceleratorErrorResponse'}}}
                    description: 'Not Found'
                '422':
                    description: 'Validation Error'
                    content: {application/json: {schema: {$ref: '#/components/schemas/HTTPValidationError'}}}
                '429':
                    content: {application/json: {schema: {$ref: '#/components/schemas/XceleratorErrorResponse'}}}
                    description: 'Too Many Requests'
components:
    schemas:
        Asset:
            properties:
                id:
                    type: string
                    title: id
                    description: 'Unique identifier of an asset.'
                    examples: [class999_9990042]
                features:
                    allOf: [{$ref: '#/components/schemas/AssetFeatures'}]
                    title: features
                    description: 'Features of an asset.'
            type: object
            required:
                - id
                - features
            title: Asset
        AssetCollectionResponse:
            properties:
                data:
                    anyOf: [{items: {$ref: '#/components/schemas/Asset'}, type: array}, {type: 'null'}]
                    title: data
                    description: 'Representation of a collection of assets.'
                    default: []
            type: object
            title: AssetCollectionResponse
            examples:
                -
                    data: [{features: {gps: {timestamp: 1712138521755, value: {latitude: 47.13250212, longitude: 17.29790506}}, mileage: {timestamp: 1712138521755, value: 246441.4}, speed: {timestamp: 1712138521755, value: 132.6}, trip: {timestamp: 1712138521755, value: {tripId: '41483'}}, uic: {value: '928012184554'}}, id: class999_9990042}]
        AssetCumulatedUpload:
            properties:
                size:
                    type: integer
                    title: value
                    description: 'Ever increasing counter for the size of the uploaded data in bytes'
                    examples: ['4711815']
            type: object
            required:
                - size
            title: AssetCumulatedUpload
        AssetDefinition:
            properties:
                value:
                    type: string
                    pattern: '[0-9a-z_]+:[0-9a-zA-Z]+'
                    title: identifier
                    description: 'Key identifier for metadata'
                    examples: ['vectron:udX4', 'dhcisr:udhcisr4', 'test:a']
            type: object
            required:
                - value
            title: AssetDefinition
        AssetDirectionTimestamped:
            properties:
                timestamp:
                    type: integer
                    maximum: 5000000000000
                    minimum: 1000000000000
                    format: int64
                    title: timestamp
                    description: 'Timestamp of the measurement or calculation of the feature in milliseconds since UTC.'
                    examples: [1712138521755]
                headCoachIdentifier:
                    type: string
                    minLength: 1
                    title: headCoachIdentifier
                    description: 'Identifier of head coach indicating the direction of movement'
                    examples: [coach_01, coach_12]
            type: object
            required:
                - timestamp
                - headCoachIdentifier
            title: AssetDirectionTimestamped
        AssetFeatures:
            properties:
                gps:
                    anyOf: [{$ref: '#/components/schemas/AssetGPSPositionTimestamped'}, {type: 'null'}]
                    title: gps
                    description: 'Information about the position of an asset.'
                    external: features.gps
                    restrict: '#gps'
                    serialize: gps
                mileage:
                    anyOf: [{$ref: '#/components/schemas/AssetMileageTimestamped'}, {type: 'null'}]
                    title: mileage
                    description: 'Information about the mileage of an asset.'
                    external: features.mileage
                    restrict: '#mil'
                    serialize: mil
                speed:
                    anyOf: [{$ref: '#/components/schemas/AssetSpeedTimestamped'}, {type: 'null'}]
                    title: speed
                    description: 'Information about the speed of an asset.'
                    external: features.speed
                    restrict: '#spd'
                    serialize: spd
                trip:
                    anyOf: [{$ref: '#/components/schemas/AssetTripTimestamped'}, {type: 'null'}]
                    title: trip
                    description: 'Information about the current trip of an asset.'
                    external: features.trip
                    restrict: '#trip'
                    serialize: trp
                uic:
                    anyOf: [{$ref: '#/components/schemas/AssetUIC'}, {type: 'null'}]
                    title: uic
                    description: 'UIC identifier of the asset.'
                    external: features.uic
                    restrict: '#uic'
                    serialize: uic
            type: object
            title: AssetFeatures
            examples:
                -
                    gps: {timestamp: 1712138521755, value: {latitude: 47.13250212, longitude: 17.29790506}}
                    mileage: {timestamp: 1712138521755, value: 246441.4}
                    speed: {timestamp: 1712138521755, value: 132.6}
                    trip: {timestamp: 1712138521755, value: {tripId: '41483'}}
                    uic: {value: '928012184554'}
        AssetGPSPositionTimestamped:
            properties:
                timestamp:
                    type: integer
                    maximum: 5000000000000
                    minimum: 1000000000000
                    format: int64
                    title: timestamp
                    description: 'Timestamp of the measurement or calculation of the feature in milliseconds since UTC.'
                    examples: [1712138521755]
                value:
                    additionalProperties: {type: number}
                    type: object
                    title: gpsPosition
                    description: 'Gives the latitude and longitude co-ordinates of the vehicle'
                    examples: [{latitude: 47.13250212, longitude: 17.29790506}]
            type: object
            required:
                - timestamp
                - value
            title: AssetGPSPositionTimestamped
        AssetLastUpload:
            properties:
                utc:
                    type: integer
                    title: utc
                    description: 'Milliseconds since UTC of last uploaded data'
                    examples: ['1700568339123']
            type: object
            required:
                - utc
            title: AssetLastUpload
        AssetMileageTimestamped:
            properties:
                timestamp:
                    type: integer
                    maximum: 5000000000000
                    minimum: 1000000000000
                    format: int64
                    title: timestamp
                    description: 'Timestamp of the measurement or calculation of the feature in milliseconds since UTC.'
                    examples: [1712138521755]
                value:
                    type: number
                    minimum: 0
                    title: mileage
                    description: 'Mileage of the asset. Unit depending on delivery region and OEM specifications either according to the imperial system (miles) or metric system (kilometers).'
                    examples: [246441.4]
            type: object
            required:
                - timestamp
                - value
            title: AssetMileageTimestamped
        AssetOccupancySource:
            type: string
            enum:
                - weight_coach
                - weight_jacobs_bogie
                - cctv
                - pcs
                - other
            title: AssetOccupancySource
        AssetOccupancyTimestamped:
            properties:
                timestamp:
                    type: integer
                    maximum: 5000000000000
                    minimum: 1000000000000
                    format: int64
                    title: timestamp
                    description: 'Timestamp of the measurement or calculation of the feature in milliseconds since UTC.'
                    examples: [1712138521755]
                overallOccupancy:
                    allOf: [{$ref: '#/components/schemas/Occupancy'}]
                    title: overallOccupancy
                    description: 'Aggregated information about the overall occupancy across all coaches.'
                coachOccupancies:
                    anyOf: [{items: {$ref: '#/components/schemas/CoachOccupancy'}, type: array}, {type: 'null'}]
                    title: coachOccupancies
                    description: 'Information about the occupancy of the individual coaches.'
                gps:
                    anyOf: [{$ref: '#/components/schemas/AssetGPSPositionTimestamped'}, {type: 'null'}]
                    title: gps
                    description: 'Information about the position of an asset during occupancy measurement.'
                source:
                    allOf: [{$ref: '#/components/schemas/AssetOccupancySource'}]
                    title: source
                    description: 'Source of the occupancy information.'
                    examples: [other]
            type: object
            required:
                - timestamp
                - overallOccupancy
                - source
            title: AssetOccupancyTimestamped
        AssetOwnerTimestamped:
            properties:
                timestamp:
                    type: integer
                    maximum: 5000000000000
                    minimum: 1000000000000
                    format: int64
                    title: timestamp
                    description: 'Timestamp of the measurement or calculation of the feature in milliseconds since UTC.'
                    examples: [1712138521755]
                value:
                    type: string
                    maxLength: 80
                    minLength: 1
                    title: owner
                    description: 'Owner of the asset.'
                    examples: [SampleOwner]
            type: object
            required:
                - timestamp
                - value
            title: AssetOwnerTimestamped
        AssetResponse:
            properties:
                data:
                    anyOf: [{$ref: '#/components/schemas/Asset'}, {type: 'null'}]
                    title: data
                    description: 'Representation of a specific asset.'
            type: object
            title: AssetResponse
            examples:
                -
                    data: {features: {gps: {timestamp: 1712138521755, value: {latitude: 47.13250212, longitude: 17.29790506}}, mileage: {timestamp: 1712138521755, value: 246441.4}, speed: {timestamp: 1712138521755, value: 132.6}, trip: {timestamp: 1712138521755, value: {tripId: '41483'}}, uic: {value: '928012184554'}}, id: class999_9990042}
        AssetSpeedTimestamped:
            properties:
                timestamp:
                    type: integer
                    maximum: 5000000000000
                    minimum: 1000000000000
                    format: int64
                    title: timestamp
                    description: 'Timestamp of the measurement or calculation of the feature in milliseconds since UTC.'
                    examples: [1712138521755]
                value:
                    type: number
                    minimum: 0
                    title: speed
                    description: 'Speed of the asset. Unit depending on delivery region and OEM specifications either according to the imperial system (miles per hour) or metric system (kilometers per hour).'
                    examples: [132.6]
            type: object
            required:
                - timestamp
                - value
            title: AssetSpeedTimestamped
        AssetTesterTimestamped:
            properties:
                timestamp:
                    type: integer
                    maximum: 5000000000000
                    minimum: 1000000000000
                    format: int64
                    title: timestamp
                    description: 'Timestamp of the measurement or calculation of the feature in milliseconds since UTC.'
                    examples: [1712138521755]
                valueStr:
                    type: string
                    maxLength: 80
                    minLength: 1
                    title: valueStr
                    description: 'String value test storage'
                    examples: ['example data']
                valueInt:
                    type: integer
                    title: valueInt
                    description: 'Integer value test storage.'
                    examples: [42]
                    max: 100000
                    min: 0
            type: object
            required:
                - timestamp
                - valueStr
                - valueInt
            title: AssetTesterTimestamped
        AssetTripTimestamped:
            properties:
                timestamp:
                    type: integer
                    maximum: 5000000000000
                    minimum: 1000000000000
                    format: int64
                    title: timestamp
                    description: 'Timestamp of the measurement or calculation of the feature in milliseconds since UTC.'
                    examples: [1712138521755]
                value:
                    additionalProperties: {type: string}
                    type: object
                    title: tripInfo
                    description: 'Holds info regarding identifier of the current trip based on manual input by the driver. Also other infolike trip start point and destination etc.'
                    examples: [{tripId: '41483'}]
            type: object
            required:
                - timestamp
                - value
            title: AssetTripTimestamped
        AssetUIC:
            properties:
                value:
                    type: string
                    pattern: '[0-9]{12}'
                    title: uicId
                    description: 'UIC identifier of the asset.'
                    examples: ['928012184554', '947004010015']
            type: object
            required:
                - value
            title: AssetUIC
        CoachOccupancy:
            properties:
                coachIdentifier:
                    type: string
                    minLength: 3
                    title: coachIdentifier
                    description: 'Unique identifier of a coach.'
                    examples: [coach_01]
                occupiedSeats:
                    type: integer
                    minimum: 0
                    format: int32
                    title: occupiedSeats
                    description: 'Number of currently occupied seats.'
                    examples: [42]
                totalSeats:
                    type: integer
                    minimum: 0
                    format: int32
                    title: totalSeats
                    description: 'Total number of seats.'
                    examples: [100]
                occupiedStandingSpots:
                    type: integer
                    minimum: 0
                    format: int32
                    title: occupiedStandingSpots
                    description: 'Number of currently occupied standing spots.'
                    examples: [2]
                totalStandingSpots:
                    type: integer
                    minimum: 0
                    format: int32
                    title: totalStandingSpots
                    description: 'Total number of standing spots.'
                    examples: [50]
            type: object
            required:
                - coachIdentifier
                - occupiedSeats
                - totalSeats
                - occupiedStandingSpots
                - totalStandingSpots
            title: CoachOccupancy
        Fleet:
            properties:
                id:
                    type: string
                    title: id
                    description: 'Unique identifier of a fleet.'
                    examples: [class999]
                assetIds:
                    items: {type: string}
                    type: array
                    title: assetIds
                    description: 'Identifiers of all assets associated with a fleet.'
                    examples: [[class999_9990042, asset_02]]
            type: object
            required:
                - id
                - assetIds
            title: Fleet
        FleetCollectionResponse:
            properties:
                data:
                    anyOf: [{items: {$ref: '#/components/schemas/Fleet'}, type: array}, {type: 'null'}]
                    title: data
                    description: 'Representation of a collection of fleets.'
            type: object
            required:
                - data
            title: FleetCollectionResponse
            example:
                data:
                    - {assetIds: [class999_9990042, asset_02], id: class999}
        FleetResponse:
            properties:
                data:
                    anyOf: [{$ref: '#/components/schemas/Fleet'}, {type: 'null'}]
                    title: data
                    description: 'Representation of a specific fleet.'
            type: object
            required:
                - data
            title: FleetResponse
            examples:
                -
                    data: {assetIds: [class999_9990042, asset_02], id: class999}
        HTTPValidationError:
            properties:
                detail:
                    items: {$ref: '#/components/schemas/ValidationError'}
                    type: array
                    title: Detail
            type: object
            title: HTTPValidationError
        Occupancy:
            properties:
                timestamp:
                    type: integer
                    maximum: 5000000000000
                    minimum: 1000000000000
                    format: int64
                    title: timestamp
                    description: 'Timestamp of the measurement or calculation of the feature in milliseconds since UTC.'
                    examples: [1712138521755]
                occupiedSeats:
                    type: integer
                    minimum: 0
                    format: int32
                    title: occupiedSeats
                    description: 'Number of currently occupied seats.'
                    examples: [600]
                totalSeats:
                    type: integer
                    minimum: 0
                    format: int32
                    title: totalSeats
                    description: 'Total number of seats.'
                    examples: [1000]
                occupiedStandingSpots:
                    type: integer
                    minimum: 0
                    format: int32
                    title: occupiedStandingSpots
                    description: 'Number of currently occupied standing spots.'
                    examples: [40]
                totalStandingSpots:
                    type: integer
                    minimum: 0
                    format: int32
                    title: totalStandingSpots
                    description: 'Total number of standing spots.'
                    examples: [500]
            type: object
            required:
                - timestamp
                - occupiedSeats
                - totalSeats
                - occupiedStandingSpots
                - totalStandingSpots
            title: Occupancy
        ValidationError:
            properties:
                loc:
                    items: {anyOf: [{type: string}, {type: integer}]}
                    type: array
                    title: Location
                msg:
                    type: string
                    title: Message
                type:
                    type: string
                    title: 'Error Type'
            type: object
            required:
                - loc
                - msg
                - type
            title: ValidationError
        XceleratorApiError:
            properties:
                code:
                    anyOf: [{type: string}, {type: 'null'}]
                    title: code
                    description: 'Railigent X error code.'
                    example: RLGTX-000
                status:
                    anyOf: [{type: string}, {type: 'null'}]
                    title: status
                    description: 'HTTP status code.'
                    example: '000'
                title:
                    anyOf: [{type: string}, {type: 'null'}]
                    title: title
                    description: 'Summary of the error.'
                    example: 'Error summary.'
                detail:
                    anyOf: [{type: string}, {type: 'null'}]
                    title: detail
                    description: 'Detailed description of the error.'
                    example: 'Error details for client-side diagnosis.'
            type: object
            required:
                - code
                - status
                - title
                - detail
            title: XceleratorApiError
        XceleratorErrorResponse:
            properties:
                errors:
                    items: {$ref: '#/components/schemas/XceleratorApiError'}
                    type: array
                    title: errors
                    description: 'Optional error payload.'
                    example: [{code: RLGTX-000, detail: 'Error details for client-side diagnosis.', status: '000', title: 'Error summary.'}]
            type: object
            required:
                - errors
            title: XceleratorErrorResponse
            example:
                errors:
                    - {code: RLGTX-000, detail: 'Error details for client-side diagnosis.', status: '000', title: 'Error summary.'}
tags:
    -
        name: Fleets
        description: 'Endpoints for discovering available assets of eligible fleets.'
    -
        name: Assets
        description: 'Endpoints for retrieving information for specific assets or all assets of a specific fleet.'
