IRMA onAir logo

Getting Started

Use the Reporting REST-API to easily and securely retrieve Automatic Passenger Counting (APC) Data. The Reporting API contains resource collections for retrieval of stops, waypoints, door opening times, device lists and Microsoft® Excel® reports.

These are the guidelines that help you integrate the API.

You’ll succeed if you do this.

Here’s some useful information.

Something may not happen if you try and do this.

Something bad will happen if you do this.

Resource

This resource is used to retrieve Automatic Passenger Counting data from your fleet. Resource URI:

https://api.irmaonair.com/services/REST/apc/{apiVersion}/{releaseVersion}

This API reference is about the latest API Version 1.8

https://api.irmaonair.com/services/REST/apc/v1/r8

Authentication

You need to be authenticated for all API requests. You can get API credentials consisting of username and password by contacting the IRMA onAir team or your iris project manager.

Access to the REST API is secured with HTTPS (TCP port 443). As encryption protocol TLS 1.2 / TLS 1.3 is currently in use. Please ensure your API client supports TLS encryption. Accessing the REST-API through standard HTTP via TCP port 80 is not supported.

Nothing will work unless you include the credentials with each API call.

curl -u user:pw -k -X POST -H "Accept: application/json" "https://api.irmaonair.com/services/REST/apc/v1/r8/stops/demo?vehicleId=demo&opdate=2017-04-04"

HTTP Response Codes

Code Name Description
200 OK Operation successful with optional payload for requested data
401 Unauthorized Client did not provide basic authentication
403 Forbidden Invalid combination of username and password
404 Not Found Requested resource was not found
405 Method Not Allowed Syntactically invalid API resource or invalid request
406 Not Acceptable Semantically invalid API resource or invalid request
500 Internal Server Error Parsing error or missing parameters in request

All errors will return JSON payload in the following format:

{
    "error":
    {
      "code":"error code",
      "message":"message text",
      "description":"error description"
    }
}

Please see section Error Messages section for further information.

Release Notes

Change Status Description
Aggregated APC Data New Feature The API comes with new /reports/sum/{operator} method that returns aggregated counting data of the whole fleet for the purpose of connecting the API to powerful BI Cloud backends such as Microsoft Power BI. The method accepts a time range as parameter and returns passenger counts by date and by GPS-matched stops
Please see the Aggregated APC Data for further details.
Raw Data for bulk operations New Feature For loading bigger sets of counting data into BI backends, the new /stops/range/{operator} method has been introduced. It returns passenger counting data of the whole fleet by the specified time period.
Status Messages Change Vehicles with no status messages in the requested time range do not appear in the result list of the /events/{operator} API call anymore.
GTFS Stops Data Change The optional GTFS field “stop_desc” (Stop description) will be exported from now on.
GTFS Stops Data Change If stop matching is not enabled, the API call will return an empty file containing only the header.
GTFS Stops Data Change GTFS files can be extended with up to 6 custom columns to store project specific content. The new parameter withGtfsExt manages whether the additional data is exported with the API.

/agency/{operator}/stops

This resource is used to pull all nominal stops assigned to an operator as static GTFS stops list. A stop record describes a stop including id, name, coordinates and other useful attributes. The stops data is mainly used for stop matching with actual stops, recorded during operations.

Sample URI:

https://api.irmaonair.com/services/REST/apc/v1/r8/agency/demoOperator/stops
Request Input Parameters
Parameter Description Data Type Usage
withGtfsExt GTFS compliant CSV files can be extended by adding at maximum 6 additonal columns with custom input and uploaded to IRMA onAir. These additional fields will be exported, if set to true. This parameter defaults to false. xs:boolean Optional
Header Input Parameters
Parameter Description Default Usage
Accept MIME Type data format of the response. Currently following formats are supported:
text/csv
text/csv Optional
Accept-Encoding Accept Encoding compresses server responses. Either gzip or none is supported. It is strongly recommended to use gzip for reducing network traffic and transmission time. none Optional
Output Parameters

If HTTP response code is 200 the request was successful.

Data formats are explained in the Nominal Stops (GTFS) section.

curl -u user:pwd -k -X POST -H "Accept: text/csv" "https://api.irmaonair.com/services/REST/apc/v1/r8/agency/demoOperator/stops"
  HTTP/1.1 200 OK
  Date: Tue, 16 Jan 2018 15:34:37 GMT
  Content-Type: text/csv
  Transfer-Encoding: chunked
1,U Mehringdamm,52.493237,13.387003,,,,,,,,,,,
2,U Mehringdamm,52.492916,13.386450,,,,,,,,,,,
3,U Gneisenaustraße,52.491281,13.394823,,,,,,,,,,,
4,U Gneisenaustraße,52.491706,13.394764,,,,,,,,,,,
5,U Kottbusser Tor,52.499432,13.416983,,,,,,,,,,,
6,U Kottbusser Tor,52.499864,13.418138,,,,,,,,,,,

/events/{operator}/

Returns different types of status messages in case sensors run outside normal limits.

Please replace the operator placeholder with the name of the operator specified during project setup. The maximum time range that can be defined per API call is one year of data (365 days), which is the default if no time range is supplied.

Sample URI:

https://api.irmaonair.com/services/REST/apc/v1/r8/events/demoOperator
Request Input Parameters
Parameter Description Data Type Usage
vehicleId Unique vehicle identifier of a vehicle of the operator’s fleet. It can be a license plate text or a defined identifier by the operator itself. Example: “B-AT 001”, “bus-1” xs:string Optional
opdateFrom Start date for limiting the requested data set in the format: YYYY-MM-DD. Example: “2016-12-21” xs:string Optional
opdateTo End date for limiting the requested data set in the format: YYYY-MM-DD. Example: “2016-12-25” xs:string Optional
asList If true, status events are formatted as XML List, otherwise as comma separated list. xs:boolean Optional
Header Input Parameters
Parameter Description Default Usage
Accept MIME Type data format of the response. Currently following formats are supported:
application/json
application/xml
application/json Optional
Accept-Encoding Accept Encoding compresses server responses. Either gzip or none is supported. It is strongly recommended to use gzip for reducing network traffic and transmission time. none Optional
Output Parameters

If HTTP response code is 200 the request was successful.

Data formats are explained in the Status Messages section.

curl -u user:pwd -k -X POST -H "Accept: application/json" "https://api.irmaonair.com/services/REST/apc/v1/r8/events/demoOperator"
HTTP/1.1 200 OK
Date: Tue, 16 Oct 2018 13:41:27 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
{
 "events":{
    "timestamp":"2018-10-16T16:05:08+02:00",
    "version":"1.0",
    "VEHICLES":[
       {
          "vehicleId":"demoVehicle-1",
          "length":"1",
          "eventList":{
             "time":"2018-10-16T05:49:25+02:00",
             "door":"1",
             "lon":"13.531873",
             "lat":"52.456317",
             "id":"MainStation-1",
             "statusList":"10"
          }
       }
    ]
 }
}

/reports/{operator}

This resource provides EXCEL reports about operational data per vehicle and per operation date. A single report contains all stops with boardings and alightings.

Please replace the operator placeholder with the name of the operator specified during project setup. Please note that Excel reports show the official nominal stop name instead of the stop Id for better user experience.

Sample URI:

https://api.irmaonair.com/services/REST/apc/v1/r8/reports/demoOperator
Request Input Parameters

This resource does not accept any query or path parameters.

Header Input Parameters
Parameter Description Default Usage
Accept MIME Type data format of the response. Currently following formats are supported:
application/vnd.ms-excel
application/vnd.ms-excel Optional
Accept-Encoding Accept Encoding compresses server responses. Either gzip or none is supported. It is strongly recommended to use gzip for reducing network traffic and transmission time. none Optional
Output Parameters

If HTTP response code is 200 the request was successful.

The filename is included in the response as follows: Content-Disposition: attachment; filename="2017-12-22_demo_demo.xls"``

curl -u user:pwd -k -X POST -H "Accept: application/vnd.ms-excel" "https://api.irmaonair.com/services/REST/apc/v1/r8/reports/demo?vehicleId=demo&opdate=2017-12-22"
  HTTP/1.1 200 OK
  Content-Type: application/vnd.ms-excel
  Transfer-Encoding: chunked
  Content-Disposition: attachment; filename="2017-12-22_demo_demo.xls"

/reports/sum/{operator}

This resource returns summarized passenger counting data over a specified period of time. The result contains two data sets (apc and stops) of which the first one delivers summarized counting data by vehicle on a per-day basis. The second part summarizes the counting data from GPS-matched stops.

Please replace the operator placeholder with the name of the operator specified during project setup.

Sample URI:

https://api.irmaonair.com/services/REST/apc/v1/r8/reports/sum/demoOperator
Request Input Parameters
opdateFrom Start date for limiting the requested data set in the format: YYYY-MM-DD. Example: “2019-01-01” xs:string Optional
opdateTo End date for limiting the requested data set in the format: YYYY-MM-DD. Example: “2019-01-31” xs:string Optional
vehicleId Add a unique vehicle identifier to return data from only one vehicle, instead of the whole fleet. It can be a license plate text or a defined identifier by the operator itself. Example: “demoVehicle” xs:string Optional

The time range is limited to cover a period of at maximum 100 days. If the parameters are not specified, the current date of the users time zone will be used.

Header Input Parameters
Parameter Description Default Usage
Accept MIME Type data format of the response. Currently following formats are supported:
application/json,
application/xml
application/json Optional
Accept-Encoding Accept Encoding compresses server responses. Either gzip or none is supported. It is strongly recommended to use gzip for reducing network traffic and transmission time. none Optional
Output Parameters

If HTTP response code is 200 the request was successful.

Data formats are explained in the Aggregated APC Data section.

curl -u user:pwd -k -X POST "https://api.irmaonair.com/services/REST/apc/v1/r8/reports/sum/demoOperator?opdateFrom=2019-02-04&opdateTo=2019-02-05&vehicleId=demoVehicle"
    HTTP/1.1 200 OK
    Date: Mon, 04 Mar 2019 12:37:39 GMT
    Content-Type: application/json
    Transfer-Encoding: chunked
    Connection: keep-alive
{
"apc":{
    "timestamp":"2019-03-04T14:06:19+01:00",
    "version":"0.1",
    "VEHICLE":{
    "operator":"demoOperator",
    "vehicleId":"demoVehicle",
    "time":"2019-03-04T14:06:19+01:00",
    "opDays":[
        {
        "date":"2019-02-04",
        "stops":"155",
        "stopsM":"1",
        "apc":[
            {
            "door":"1",
            "catId":"0",
            "in":"161",
            "out":"50"
            }
        ]
        },
        {
        "date":"2019-02-05",
        "stops":"352",
        "stopsM":"1",
        "apc":[
            {
            "door":"1",
            "catId":"0",
            "in":"538",
            "out":"67"
            }
        ]
        }
    ]
    },
    "stops":[
    {
        "date":"2019-02-04",
        "apcStops":[
        {
            "id":"sampleStop",
            "stops":"1",
            "apc":{
            "door":"2",
            "catId":"0",
            "in":"0",
            "out":"1"
            }
        }
        ]
    },
    {
        "date":"2019-02-05",
        "apcStops":[
        {
            "id":"sampleStop",
            "stops":"1",
            "apc":{
            "door":"5",
            "catId":"0",
            "in":"0",
            "out":"7"
            }
        }
        ]
    }
    ]
}
}

/stops/{operator}/

The stops/{operator}/ resource return stops data of the fleet for a selected operation date on a vehicle basis. Each vehicle record comes with a listing of stop records in descending order, each of them containing the counting data for a specific stop.

Please replace the operator placeholder with the name of the operator specified during project setup.

Sample URI:

https://api.irmaonair.com/services/REST/apc/v1/r8/stops/demoOperator
Request Input Parameters
Parameter Description Data Type Usage
vehicleId Unique vehicle identifier of a vehicle of the operator’s fleet. It can be a license plate text or a defined identifier by the operator itself. Example: “B-AT 001”, “bus-1” xs:string Optional
opdate Operation date of the selected vehicle in the format: YYYY-MM-DD. Example: “2016-12-21” xs:string Optional
doorLengthOnly If set to true Door Opening Times are calculated after a vehicle has let a stop (immutable data sets, safe mode).
If set to false Door Opening Times are calculated during a stop and may be re-calculated and transmitted several times (mutable data sets, real-time mode).
Defaults to false.
xs:string Optional
limit Upper limit for the number of returned records. Example: “10” . Retrieves the latest 10 APC records of the selected operation date in descending order xs:int Optional

By default, this call will return the stops data of the whole fleet for the selected operation date. The operation date defaults to the current date, if not set explicitly.

Header Input Parameters
Parameter Description Default Usage
Accept MIME Type data format of the response. Currently following formats are supported:
application/json
application/xml
text/csv
text/csv Optional
Accept-Encoding Accept Encoding compresses server responses. Either gzip or none is supported. It is strongly recommended to use gzip for reducing network traffic and transmission time. none Optional
Output Parameters

If HTTP response code is 200 the request was successful.

If request header parameter is of MIME type “Accept: text/csv”, then filename is included as follows: Content-Disposition: attachment; filename="YYYY-MM-DD_operator_vehicleId.csv"``

Data formats are explained in the Actual Stops (VDV 457-2) section.

curl -u user:pwd -k -X POST -H "Accept: application/json" "https://api.irmaonair.com/services/REST/apc/v1/r8/stops/demo?vehicleId=demo&opdate=2017-06-01"
HTTP/1.1 200
Date: Fri, 13 Oct 2017 14:17:50 GMT
Content-Encoding: gzip
Vary: Accept-Encoding
Content-Type: application/json
Transfer-Encoding: chunked
{
   "VDV457":{
      "timestamp":"2017-10-13T12:50:19Z",
      "version":"0.1",
      "VEHICLE":{
         "operator":"demo",
         "vehicleId":"demo",
         "time":"2017-10-13T12:50:19Z",
         "stop":[
            {
               "type":"1",
               "timeStart":"2017-06-01T19:10:15Z",
               "timeStop":"2017-06-01T19:10:15Z",
               "lon":"14.0995958",
               "lat":"51.0466250",
               "apc":{
                  "door":"1",
                  "catId":"0",
                  "in":"4",
                  "out":"4"
               }
            },
            {
               "type":"1",
               "timeStart":"2017-06-01T18:59:59Z",
               "timeStop":"2017-06-01T18:59:59Z",
               "lon":"14.0801492",
               "lat":"51.0505408"
            }
         ]
      }
   }
}

/stops/{operator}/update

The update sub resource is used for retrieval of stop updates by specifying a time range for which the APC data will be returned. The maximum time range is 7 days in the past.

Sample URI:

https://api.irmaonair.com/services/REST/apc/v1/r8/stops/demoOperator/update

The use of the update sub resource is limited to accept payload of content type application/json only at the moment. The header and request input parameters of the stops resource still apply.

The update resource requires a json payload to be sent with each request. The payload is specifying the vehicle identifiers for whom stop updates shall be returned in the response. The time range is defined as the time between current system timestamp and the value of the timeStamp field provided with each vehicle record.

Payload example #1

    {
        "update": {
            "vehicles": [{
                "vehicleId": "demo-1",
                "timeStamp": "2018-04-23T13:59:41+02:00"
            },{
                "vehicleId": "demo-2",
                "timeStamp": "2018-04-23T12:40:32+02:00"
            }]
        }
    }

To address all vehicles of the fleet the update tag should remain empty. The response will include the data of the last 7 days.

Payload example #2

    {
        "update":{ }
    }

The most recent timestamp per vehicle that is received with the response is meant to be put into the following request again. By doing this an API client will always retrieve exactly that pieces of data that have not been processed yet. When there are no new data available, then the stop listing of the response will be empty.

If a vehicleId cannot be recognized or is not associated to the operator, then the vehicle record of the response contains an error field containing the value 1.

Wrong vehicle Id

{
    "vehicleId": "wrongVehicleId",
    "operator": "demo",
    "error": "1",
    "stop": []
}
Request Input Parameters
Parameter Description Default Usage
addMissing Boolean value that, if set true, enforces the export of stops data of the whole fleet with each request. Vehicles that have been added to the fleet while the API client is up & running, can be detected and added to the main loop. false Optional

If HTTP response code is 200 the request was successful.

Data formats are explained in the Actual Stops (VDV 457-2) section.

  curl -u user:pwd -k -X POST -H "Accept: application/json" -H "content-type: application/json" "https://api.irmaonair.com/services/REST/apc/v1/r8/stops/demoOperator/update" -d "{\"update\":{}}"
HTTP/1.1 200
Date: Fri, 13 Oct 2017 14:17:50 GMT
Content-Encoding: gzip
Vary: Accept-Encoding
Content-Type: application/json
Transfer-Encoding: chunked
{
   "VDV457":{
      "timestamp":"2017-10-13T12:50:19Z",
      "version":"0.1",
      "VEHICLE":{
         "operator":"demo",
         "vehicleId":"demo",
         "time":"2017-10-13T12:50:19Z",
         "stop":[
            {
               "type":"1",
               "timeStart":"2017-06-01T19:10:15Z",
               "timeStop":"2017-06-01T19:10:15Z",
               "lon":"14.0995958",
               "lat":"51.0466250",
               "apc":{
                  "door":"1",
                  "catId":"0",
                  "in":"4",
                  "out":"4"
               }
            },
            {
               "type":"1",
               "timeStart":"2017-06-01T18:59:59Z",
               "timeStop":"2017-06-01T18:59:59Z",
               "lon":"14.0995958",
               "lat":"51.0466250"
            }
         ]
      }
   }
}

/stops/range/{operator}/

The stops/range/{operator}/ method returns counting data of a user-defined time range for the whole fleet.

Please replace the operator placeholder with the name of the operator specified during project setup.

Sample URI:

https://api.irmaonair.com/services/REST/apc/v1/r8/stops/range/demoOperator
Request Input Parameters
opdateFrom Start date for limiting the requested data set in the format: YYYY-MM-DD. Example: “2019-01-01” xs:string Optional
opdateTo End date for limiting the requested data set in the format: YYYY-MM-DD. Example: “2019-01-31” xs:string Optional
vehicleId Add a unique vehicle identifier to return data from only one vehicle, instead of the whole fleet. It can be a license plate text or a defined identifier by the operator itself. Example: “demoVehicle” xs:string Optional

The time range is limited to cover a period of at maximum 100 days. If the parameters are not specified, the current date of the users time zone will be used.

Header Input Parameters
Parameter Description Default Usage
Accept MIME Type data format of the response. Currently following formats are supported:
application/json,
application/xml
application/json Optional
Accept-Encoding Accept Encoding compresses server responses. Either gzip or none is supported. It is strongly recommended to use gzip for reducing network traffic and transmission time. none Optional
Output Parameters

If HTTP response code is 200 the request was successful.

Data formats are explained in the Actual Stops (VDV 457-2) section.

curl -u user:pwd -k -X POST -H "Accept: application/json" "https://api.irmaonair.com/services/REST/apc/v1/r8/stops/range/demoOperator?opdateFrom=2019-01-01&opdateTo=2019-01-31"
 HTTP/1.1 200 OK
 Date: Mon, 04 Mar 2019 12:37:39 GMT
 Content-Type: application/json
 Transfer-Encoding: chunked
 Connection: keep-alive
 {
 "VDV457":{
    "timestamp":"2019-03-06T09:37:21+01:00",
    "version":"0.1",
    "VEHICLE":[
       {
       "vehicleId":"demoVehicle01",
       "operator":"demoOperator",
       "time":"2019-03-06T09:37:21+01:00",
       "stop":[
          {
             "type":"1",
             "timeStart":"2019-01-02T16:18:10+01:00",
             "timeStop":"2019-01-02T16:18:10+01:00",
             "lon":"14.0995958",
             "lat":"51.0466250",
             "apc":[
             {
                "door":"1",
                "catId":"0",
                "in":"2",
                "out":"2"
             },
             {
                "door":"2",
                "catId":"0",
                "in":"0",
                "out":"0"
             }
             ]
          },
          // here: several more stops covering the specified time range...
       ]
       },
       {
       "vehicleId":"demoVehicle02",
       "operator":"demoOperator",
       "time":"2019-03-06T09:37:21+01:00",
       "stop":[
          {
             "type":"1",
             "timeStart":"2019-01-02T20:44:39+01:00",
             "timeStop":"2019-01-02T20:44:39+01:00",
             "lon":"14.0995958",
             "lat":"51.0466250",
             "apc":{
             "door":"1",
             "catId":"0",
             "in":"0",
             "out":"0"
             }
          },
          // here: several more stops covering the specified time range...
       ]
       },
       // here: other vehicles ...
    ]
 }
 }

/tracks/{operator}/

The /tracks/{operator} resource returns a set of waypoint records in descending order. Vehicle identifier and operation date serve as mandatory input parameters. A waypoint is a geolocation record generated while the vehicle is driving between two subsequent stops. A waypoint is comprised of a GNSS geolocation and a timestamp.

Please replace the operator placeholder with the name of the operator specified during project setup.

Sample URI:

https://api.irmaonair.com/services/REST/apc/v1/r8/tracks/demoOperator
Request Input Parameters
Parameter Description Data Type Usage
vehicleId Unique vehicle identifier of a vehicle of the operator’s fleet. It can be a license plate text or a defined identifier by the operator itself. Example: “B-AT 001”, “bus-1” xs:string Mandatory
opdate Operation date of the selected vehicle in the format: YYYY-MM-DD. Example: “2016-12-21” xs:string Optional
limit Upper limit for the number of returned records. Example: “10” . Retrieves the latest 10 APC records of the selected operation date in descending order xs:int Optional
withMotion Allows to request additional attributes speed v, altitude alt, azimuth azi.
If the Hardware is not configured to provide such values, the defaults are v:-1.0,azi:32767,alt:32767.
If GPS is not available due to signal quality issues, defaults are v:0.0,azi=0,alt:16384
xs:boolean Optional

By default, this call will return all counting events for the selected operation date. The operation date defaults to the current date.

Header Input Parameters
Parameter Description Default Usage
Accept MIME Type data format of the response. Currently following formats are supported:
application/json
application/xml
application/json Optional
Accept-Encoding Accept Encoding compresses server responses. Either gzip or none is supported. It is strongly recommended to use gzip for reducing network traffic and transmission time. none Optional
Output Parameters

If HTTP response code is 200 the request was successful.

Data formats are explained in the Waypoints section.

curl -u user:pwd -k -X POST -H "Accept: application/json" "https://api.irmaonair.com/services/REST/apc/v1/r8/tracks/demo?vehicleId=demo&opdate=2017-06-01"
HTTP/1.1 200
Date: Fri, 13 Oct 2017 14:17:50 GMT
Content-Type: application/json
Transfer-Encoding: chunked
{
  "track":{
    "firstTimestamp":"2017-06-01T20:00:46Z",
    "lastTimestamp":"2017-06-01T20:01:07Z",
    "length":"2",
    "operator":"demo",
    "vehicleId":"demo",
    "wayPoints":[{
          "time":"2017-06-01T20:01:07Z",
          "lat":"51.0466833",
          "lon":"14.0996633"
        },
        {
          "time":"2017-06-01T20:00:46Z",
          "lat":"51.0466983",
          "lon":"14.0996425"
        }
      ]
    }
  }

/user/devices

This resource is used to retrieve information about a fleet and it's vehicles. The fleet data is resolved by the user credentials used to request the resource, because it is associated with fleet and tenant information.

Sample URI:

https://api.irmaonair.com/services/REST/apc/v1/r8/user/devices
Request Input Parameters

This resource does not accept any query or path parameters.

Header Input Parameters
Parameter Description Default Usage
Accept MIME Type data format of the response. Currently following formats are supported:
application/json
application/json Optional
Accept-Encoding Accept Encoding compresses server responses. Either gzip or none is supported. It is strongly recommended to use gzip for reducing network traffic and transmission time. none Optional
Output Parameters

If HTTP response code is 200 the request was successful.

Data formats are explained in the Devices section.

curl -u user:pwd -k -X POST -H "Accept: application/json" "https://api.irmaonair.com/services/REST/apc/v1/r8/user/devices"
  HTTP/1.1 200 OK
  Date: Tue, 16 Jan 2018 15:34:37 GMT
  Content-Type: application/json
  Transfer-Encoding: chunked
{
    "mydevices":{
      "operators":{
          "name":"demoOperator",
          "shortName":"demoOp",
          "longName":"Operator for demo purposes",
          "email":"demo@demo.com",
          "language":"de-DE",
          "timeZone":"Europe/Berlin",
          "devices":[
            {
                "serialnumber":"123456789",
                "vehicleid":"demoVehicle-1",
                "doors":"2",
                "categories":"0"
            },
            {
                "serialnumber":"987654321",
                "vehicleid":"demoVehicle-2",
                "doors":"3",
                "categories":[
                  "0",
                  "1"
                ]
            }
          ]
      }
    }
}

General Information

IRMA onAir Reporting API is an implementation of VDV 457-2 (v2.0, published in 2015).

VDV 457 is a German standard for the implementation of APC systems created by the VDV organization (Association of German Transport Companies). Section VDV 457-2 2.0 which was released in 06/2015 is about the data exchange between an APC system and the central backend system. IRMA onAir Reporting API is an implementation of the autonomous profile of VDV 457-2 that allows exchanging APC raw data without the need of additional scheduling data.

Currently the representation of APC records is implemented according to VDV 457-2 standard. Waypoint data and meta data formats are propietary due to the fact that they are not covered by the standard.

The following sections guide you through the data formats used to exchange data between IRMA onAir Reporting API and software clients retrieving APC data from the platform. The data is available in the following formats:

  • JSON (JavaScript Object Notation)
  • XML (Extensible Markup Language)
  • CSV (Comma-Separated Values)

The data formats are suitable for retrieving APC data, Waypoint Data and Meta Data about the fleet. A predefined representation of a vehicle journey is available in the Microsoft® Excel® format.

Actual Stops (VDV 457-2)

Document Header (VDV-457)

The header is comprised of the timestamp when the document was created and the data interface version.

Field Description Data type Example
timestamp Timestamp of document created xs:datetime 2016-12-01T09:51:17+02:00
version Identifier for current data interface version xs:string 0.1

For JSON and XML “VDV457” serves as the root element.

The first line of CSV documents contains the document header.

Vehicle Header (VEHICLE)

A vehicle header wraps a list of APC records that represent the vehicle’s journey on a specific operation date. The vehicle header consists of the operator identifier, the vehicle identifier and the timestamp when the current record was created.

Field Description Data type Example
operator Short name of the operator as specified during project setup xs:string demoOperator
vehicleId The identifier of the vehicle as specified during project setup. If not specified, IRMA Hub device Id is returned. xs:string demoVehicle
time Timestamp of record created xs:datetime 2016-12-01T09:51:18+02:00

The second line of the CSV document contains the vehicle record header. It starts with a “VEHICLE” tag, because vehicle headers can occur multiple times within a document, each one representing the beginning of a new vehicle record.

Stop Record (stop)

A stop record contains the data of an actual stop recorded during the trip. Passenger Counting data are split into boardings and alightings, but also further into Counting Categories (Adults, Children, Wheelchair and Bikes). GNSS locations and door opening times, together with Counting Data, make up the whole record.

Field Description Data type Example
type Actual stop detected = 1 xs:int 1
id The unique identifier of a stop or station if stop matching feature is activated. If stop could not be matched, the field remains empty. xs:string StopABC123
timeStart Time of earliest door opening event as timestamp including time zone. xs:datetime 2016-01-01T01:01:01+02:00
timeStop Time of latest door opening event as timestamp including time zone. xs:datetime 2016-01-01T01:02:01+02:00
lon GPS x-coordinate (longitude) of the stop. Coordinates are represented in WGS84 decimal format. xs:string 14.0995958
lat GPS y-coordinate (latitude) of the stop. Coordinates are represented in WGS84 decimal format. xs:string 51.0466250

APC record (apc)

Each Stop record contains [0..n] APC records depending on the number of doors. An APC record provides Passenger Counting data per Door and per Counting Category and split into boardings and alightings. Only when there is passenger traffic at the doors, APC data will be available. In case doors remain closed, no data is exported. When there are zero (“0”) boardings or alightings, it means the APC system was online while the doors were open, but no one entered or left the vehicle.

Field Description Data type Example
door Unique door number within a vehicle, door numbers will be incremented starting from 1 (1..n) xs:int 1
catId Counting category (only if configured on the APC system):
0 = Adults
1 = Children
2 = Bike
3 = Stroller (reserved for future use)
4 = Wheelchair
xs:int 0
in Number of Boardings xs:int 10
out Number of Alightings xs:int 5

APC records in CSV documents are added to the end of a line that represents a stop. The fields door, catId, in and out are separated by a semicolon. For example, two APC records consist of eight fields to be parsed by the client.

{
   "VDV457":{
      "timestamp":"2017-10-13T12:50:19Z",
      "version":"0.1",
      "VEHICLE":{
         "operator":"demo",
         "vehicleId":"demo",
         "time":"2017-10-13T12:50:19Z",
         "stop":[
            {
               "type":"1",
               "timeStart":"2017-06-01T19:10:15Z",
               "timeStop":"2017-06-01T19:10:15Z",
               "lon":"14.0995958",
               "lat":"51.0466250",
               "apc":{
                  "door":"1",
                  "catId":"0",
                  "in":"4",
                  "out":"4"
               }
            },
            {
               "type":"1",
               "timeStart":"2017-06-01T18:59:59Z",
               "timeStop":"2017-06-01T18:59:59Z",
               "lon":"14.0801492",
               "lat":"51.0505408"
            }
         ]
      }
   }
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VDV457>
  <timestamp>2018-05-25T12:09:33Z</timestamp>
  <version>0.1</version>
  <VEHICLES>
    <VEHICLE>
      <operator>demo</operator>
      <time>2018-05-25T12:09:33Z</time>
      <stops>
        <stop>
         <type>1</type>
         <timeStart>2017-06-01T19:10:15Z</timeStart>
         <timeStop>2017-06-01T19:10:15Z</timeStop>
         <lon>14.0995958</lon>
         <lat>51.0466250</lat>
         <apcData>
            <apc>
              <door>1</door>
              <catId>0</catId>
              <in>4</in>
              <out>4</out>
            </apc>
          </apcData>
        </stop>
      </stops>
      <vehicleId>demo</vehicleId>
    </VEHICLE>
  </VEHICLES>
</VDV457>
2018-01-22T13:01:07Z;0.1
VEHICLE;demo;demo;2018-01-22T13:01:07Z
1;;2017-06-01T19:10:15Z;2017-06-01T19:10:15Z;14.0995958;51.0466250;1;0;4;4
1;;2017-06-01T18:51:34Z;2017-06-01T18:51:34Z;14.0029583;51.0283250;1;0;0;1
1;;2017-06-01T18:49:25Z;2017-06-01T18:49:25Z;13.9916708;51.0354025;2;0;0;1
1;;2017-06-01T18:34:49Z;2017-06-01T18:34:49Z;13.8870850;51.0354350;1;0;0;1
1;;2017-06-01T18:32:24Z;2017-06-01T18:32:24Z;13.8780033;51.0424800;2;0;0;1
1;;2017-06-01T18:30:20Z;2017-06-01T18:30:20Z;13.8702183;51.0479483;2;0;0;1

Aggregated APC Data

Document Header

The header is comprised of the timestamp when the document was created and the data interface version.

Field Description Data type Example
timestamp Timestamp of document created xs:datetime 2016-12-01T09:51:17+02:00
version Identifier for current data interface version xs:string 0.1

For JSON and XML “apc” serves as the root element. For XML “VEHICLES” wraps counting data per day per vehicle and “stop” wraps counting data summarized per day at a nominal stop.

The root element “apc” contains two list elements. The first element “VEHICLES” contains summarized counting data per date per vehicle. The second element “stop” contains summarized data at GPS matched nominal stop for each date, e.g. at “sampleStop” on date 2019-02-04:


1000 ins and 1040 outs in total and summarized from 100 stops were counted at door 1.

This includes the ins and outs by all vehicles stopped at this “Sample Stop”.

Vehicle List (VEHICLE)

The vehicles section contains the summary of the counting data of the specified time range by vehicle. Each vehicle record consists of the operator identifier, the vehicle identifier and the timestamp when the current record was created. Additionally, it stores a list of the operation days, containing the counting data.

Field Description Data type Example
operator Short name of the operator as specified during project setup xs:string demoOperator
vehicleId The identifier of the vehicle as specified during project setup. If not specified, IRMA Hub device Id is returned. xs:string demoVehicle
time Timestamp of record created xs:datetime 2016-12-01T09:51:18+02:00

In XML documents the “VEHICLES” tags wraps all vehicle “VEHICLE” records.

Operation days (opDays)

An operation day record contains the summarized counting data per date, number of served stops and served GPS-matched stops.

Field Description Data type Example  
date Date Operation date of the format YYYY-MM-DD xs:string 2016-12-21
stops Number of stops served during the operation day xs:int 155  
stopsM Number of served GPS-matched stops during the operation day xs:int 151  

In XML documents the “opDays” tags wraps all vehicle “opDay” records.

Counting records (apc)

Field Description Data type Example
door Unique door number within a vehicle, door numbers will be incremented starting from 1 (1..n) xs:int 1
catId Counting category (only if configured on the APC system):
0 = Adults
1 = Children
2 = Bike
3 = Stroller (reserved for future use)
4 = Wheelchair
xs:int 0
in Number of Boardings xs:int 10
out Number of Alightings xs:int 5

In XML documents the “apcData” tags wraps all vehicle “apc” records.

{
"apc":{
   "timestamp":"2019-03-04T14:06:19+01:00",
   "version":"0.1",
   "VEHICLE":{
      "operator":"demoOperator",
      "vehicleId":"demoVehicle",
      "time":"2019-03-04T14:06:19+01:00",
      "opDays":[
      {
         "date":"2019-02-04",
         "stops":"155",
         "stopsM":"1",
         "apc":[
            {
            "door":"1",
            "catId":"0",
            "in":"161",
            "out":"50"
            }
         ]
      },
      {
         "date":"2019-02-05",
         "stops":"352",
         "stopsM":"1",
         "apc":[
            {
            "door":"1",
            "catId":"0",
            "in":"538",
            "out":"67"
            }
         ]
      }
      ]
   },
   "stops":[
      {
      "date":"2019-02-04",
      "apcStops":[
         {
            "id":"sampleStop",
            "stops":"100",
            "apc":{
            "door":"1",
            "catId":"0",
            "in":"1000",
            "out":"1040"
            }
         }
      ]
      },
      {
      "date":"2019-02-05",
      "apcStops":[
         {
            "id":"sampleStop",
            "stops":"120",
            "apc":{
            "door":"1",
            "catId":"0",
            "in":"1500",
            "out":"1470"
            }
         }
      ]
      }
   ]
}
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<apc>
   <timestamp>2019-03-04T14:26:02+01:00</timestamp>
   <version>0.1</version>
   <VEHICLES>
      <VEHICLE>
            <operator>demoOperator</operator>
            <vehicleId>demoVehicle</vehicleId>
            <time>2019-03-04T14:26:02+01:00</time>
            <opDays>
               <opDay>
                  <date>2019-02-04</date>
                  <stops>155</stops>
                  <stopsM>1</stopsM>
                  <apcData>
                        <apc>
                           <door>1</door>
                           <catId>0</catId>
                           <in>161</in>
                           <out>50</out>
                        </apc>
                  </apcData>
               </stop>
               <stop>
                  <date>2019-02-05</date>
                  <stops>352</stops>
                  <stopsM>350</stopsM>
                  <apcData>
                        <apc>
                           <door>1</door>
                           <catId>0</catId>
                           <in>538</in>
                           <out>67</out>
                        </apc>
                  </apcData>
               </stop>
            </stops>
      </VEHICLE>
   </VEHICLES>
   <stop>
      <stops>
            <date>2019-02-04</date>
            <apcStops>
               <id>sampleStop</id>
               <stops>100</stops>
               <apc>
                  <door>1</door>
                  <catId>0</catId>
                  <in>1000</in>
                  <out>1040</out>
               </apc>
            </apcStops>
      </stops>
      <stops>
            <date>sampleStop</date>
            <apcStops>
               <id>sampleStop</id>
               <stops>120</stops>
               <apc>
                  <door>1</door>
                  <catId>0</catId>
                  <in>1500</in>
                  <out>1470</out>
               </apc>
            </apcStops>
      </stops>
   </stop>
</apc>

Devices

The device listing shows the mapping of IRMA Hub serial numbers onto vehicle identifiers. A serial number identifies an IRMA Hub uniquely. The vehicle identifier is defined by third parties and reflects e.g. the license plate information.

The “mydevices” field serves as the root element when using XML.

Each devices document comes with a list of operators that is associated with the current user executing the query.

Operator Record (operators)

Field Description Data type Example
name The unique identifier of the operator to be used in other queries xs:string demoOperator
shortName The short name of the operator for display purposes xs:string demOp
longName The long name of the operator for display purposes xs:string Demo Transit Agency
email The generic email address of the operator xs:string demo@dta.org
language Language localisation according to IETF language tags xs:string de-DE
timeZone Timezone information xs:string Europe/Berlin

Device Record (devices)

Each operator record comes with a list of its devices. A single device record shows the mapping of IRMA Hub serial numbers onto vehicle identifiers.

Field Description Data type Example
serialnumber The unique serial number of IRMA Hub device xs:string 123456
vehicleId The unique vehicle identifier xs:string demoVehicle-1
doors Number of doors xs:int demoVehicle-1
categories Supported counting categories.
Full category list:
0 = Adults
1 = Children
2 = Bike
3 = Stroller (reserved for future use)
4 = Wheelchair
list of xs:int [1,2]
{
    "mydevices":{
        "operators":{
            "name":"demoOperator",
            "shortName":"demoOp",
            "longName":"Operator for demo purposes",
            "email":"demo@demo.com",
            "language":"de-DE",
            "timeZone":"Europe/Berlin",
            "devices":[
            {
                "serialnumber":"123456789",
                "vehicleid":"demoVehicle-1",
                "doors":"2",
                "categories":"0"
            },
            {
                "serialnumber":"987654321",
                "vehicleid":"demoVehicle-2",
                "doors":"3",
                "categories":[
                    "0",
                    "1"
                ]
            }
            ]
        }
    }
}    
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mydevices>
    <operators>
        <name>demoOperator</name>
        <shortName>demoOp</shortName>
        <longName>Operator for demo purposes</longName>
        <email>demo@demo.com</email>
        <language>de-DE</language>
        <timeZone>Europe/Berlin</timeZone>
        <devices>
        <device>
            <categories>
            <category>0</category>
            </categories>
            <doors>2</doors>
            <serialnumber>123456789</serialnumber>
            <vehicleid>demoVehicle-1</vehicleid>
        </device>
        <device>
            <categories>
            <category>0</category>
            <category>1</category>
            </categories>
            <doors>2</doors>
            <serialnumber>987654321</serialnumber>
            <vehicleid>demoVehicle-2</vehicleid>
        </device>
        </devices>
    </operators>
</mydevices>

Nominal Stops (GTFS)

The list of nominal stops are individual locations where vehicles pick up or drop off passengers. They are matched to the actuals stops of the fleet.

The stop list is an implementation of GTFS stops.txt, please see the Google GTFS documentation for additional information.

Nominal Stop Record

Field Description Data type Example Usage
stop_id The stop_id field contains an ID that uniquely identifies a stop, station, or station entrance. The stop_id is used by IRMA onAir as an internal identifier of this record (e.g., primary key in database), and therefore the stop_id must be dataset unique. xs:string 1 Required
stop_name The stop_name field contains the name of a stop, station, or station entrance. It contains a name that people will understand in the local and tourist vernacular. xs:string U Mehringdamm Required
stop_lat The stop_lat field contains the latitude of a stop, station, or station entrance. The field value must be a valid WGS 84 latitude. xs:string 52.493237 Required
stop_lon The stop_lon field contains the longitude of a stop, station, or station entrance. The field value must be a valid WGS 84 longitude value from -180 to 180. xs:string 13.387003 Required

All optional GTFS fields are currently neither used nor exported by IRMA onAir.

1,U Mehringdamm,52.493237,13.387003,,,,,,,,,,,
2,U Mehringdamm,52.492916,13.386450,,,,,,,,,,,
3,U Gneisenaustraße,52.491281,13.394823,,,,,,,,,,,
4,U Gneisenaustraße,52.491706,13.394764,,,,,,,,,,,
5,U Kottbusser Tor,52.499432,13.416983,,,,,,,,,,,
6,U Kottbusser Tor,52.499864,13.418138,,,,,,,,,,,

Status Messages

Status messages are recorded by the devices during operations whenever they run outside normal limits.

The “events” field serves as the root element when using XML.

Events Header (events)

The events header summarizes meta information about how and when the document was created and it holds a list of status messages grouped by vehicles.

Field Description Data type Example
timestamp Timestamp of document created xs:datetime 2018-10-16T16:05:08+02:00
version Identifier for current data interface version xs:string 0.1

Vehicle list (VEHICLES)

Field Description Data type Example
vehicleId The identifier of the vehicle as specified during project setup. If not specified, IRMA Hub device Id is returned. xs:string demoVehicle-1
length Length of the list of status messages xs:int 2

Each vehicle record contains a list of status messages as described below.

Status messages (eventList)

Field Description Data type Example
time The timestamp of when the event was recorded. xs:datetime 2018-10-16T05:49:25+02:00
door The number of the door at which the event was recorded. xs:int 1
lon GPS x-coordinate (longitude) of the event location. Coordinates are represented in WGS84 decimal format. xs:string 13.531873
lat GPS y-coordinate (latitude) of the event location. Coordinates are represented in WGS84 decimal format. xs:string 52.456317
id Stop id of the event location. Requires activated stop matching and may also be empty, in case no near stop could be resolved. xs:string MainStation-1
statusList List of status messages by their id. Depending on the request parameter, the list can be represented either as XML list or as a comma separated list. The full list of available messages:
1 = Sabotage
4 = Service Mode active
7 = Overtemperature detected (The maximum temperature was exceeded at least once.)
8 = Overtemperature still active
10 = Undervoltage detected
list of xs:string 10,4
{
    "events":{
        "timestamp":"2018-10-16T16:05:08+02:00",
        "version":"1.0",
        "VEHICLES":[
        {
            "vehicleId":"demoVehicle-1",
            "length":"1",
            "eventList":{
                "time":"2018-10-16T05:49:25+02:00",
                "door":"1",
                "lon":"13.531873",
                "lat":"52.456317",
                "id":"MainStation-1",
                "statusList":"10"
            }
        }
        ]
    }
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<events>
    <timestamp>2018-10-17T11:33:52+02:00</timestamp>
    <version>1.0</version>
    <VEHICLES>
        <VEHICLE>
        <vehicleId>demoVehicle-1</vehicleId>
        <length>2</length>
        <eventList>
            <event>
            <time>2018-10-16T05:49:25+02:00</time>
            <door>1</door>
            <lon>13.531873</lon>
            <lat>52.456317</lat>
            <id>MainStation-1</id>
            <statusList>
                <status>10</status>
            </statusList>
            </event>
        </eventList>
        </VEHICLE>
    </VEHICLES>
</events>

Waypoints

Waypoints are geolocations recorded between actual stops. The data can easily be used for GPS tracking or for matching the GNSS locations against nominal schedule data such as routes or lines.

Header Data (track)

The header is comprised of metadata describing the waypoints that are listed within the document.

Field Description Data type Example
vehicleId The identifier of the vehicle as specified during project setup. If not specified, IRMA Hub device Id is returned. xs:string demo
operator Short name of the operator as specified during project setup xs:string demo
length Number of waypoint records xs:int 2
firstTimestamp Timestamp of the oldest event within the current document xs:datetime 2018-04-30T09:25:16+02:00
lastTimestamp Timestamp of the most recent event within the current document xs:datetime 2018-04-30T17:53:01+02:00

“track” serves as the root element.

Waypoint Record (waypoints)

A single waypoint document contains a list of waypoint records, each of them describing a geolocation, recorded throughout the operation day of a selected vehicle.

Field Description Data type Example
time Timestamp of record created xs:datetime 2018-04-30T09:25:16+02:00
lat Latitude in WGS84 decimal format xs:string 51.0466250
lon Longitude in WGS84 decimal format xs:string 14.0995958
v Current speed in kmph xs:double 0.4
azi Azimuth, the horizontal angle measured clockwise from a north base line or meridian xs:int 20
alt Current altitude in meters xs:int 120
  {
    "track":{
      "vehicleId":"demo",
      "operator":"demo",
      "length":"2",
      "firstTimestamp":"2018-04-30T18:04:38+02:00",
      "lastTimestamp":"2018-04-30T18:04:50+02:00",
      "wayPoints":[
        {
            "time":"2018-04-30T18:04:50+02:00",
            "lat":"51.0467158",
            "lon":"14.0994617",
            "v":"12.5",
            "azi":"250",
            "alt":"120"
        },
        {
            "time":"2018-04-30T18:04:38+02:00",
            "lat":"51.04666992",
            "lon":"14.0994642",
            "v":"11.4",
            "azi":"240",
            "alt":"110"
        }
      ]
    }
  }
  <track>
    <firstTimestamp>2018-04-30T18:04:38Z</firstTimestamp>
    <lastTimestamp>2018-04-30T18:04:50Z</lastTimestamp>
    <length>2</length>
    <operator>demo</operator>
    <vehicleId>demo</vehicleId>
    <wayPoints>
        <wayPoint>
          <time>2018-04-30T18:04:50Z</time>
          <lat>51.0467158</lat>
          <lon>14.0994617</lon>
          <alt>32767</alt>
          <azi>32767</azi>
          <v>-1.0</v>
        </wayPoint>
        <wayPoint>
          <time>2018-04-30T18:04:38Z</time>
          <lat>51.0466992</lat>
          <lon>14.0994642</lon>
          <alt>32767</alt>
          <azi>32767</azi>
          <v>-1.0</v>
        </wayPoint>
    </wayPoints>
  </track>

Error Messages

The API is returning error messages in JSON whenever API requests have not been formulated entirely correctly.

This section covers error messages created by the API itself. The overview of all HTTP response codes can be found in the Response Codes section.

Error Messages

Code Name Meaning
500 Internal Exception Mostly parsing errors due to bad date formats or text that could not be parsed
1000 No data For selected resource and time-range no data is available
1001 No door-contact information For selected vehicle is no door contact information in database stored
1003 Date or date range specied is not valid Date is too far in future or end date before start date
2000 Unauthorized No permission to access the requested method
3001 Wrong Api Version The requested version is not supported
3002 Not compatible api version The request is not compatible with this release version
3004 Parameter Date is missing Operation Date or is missing in API request

All errors will return JSON in the following format:

{
    "error":
    {
      "code":"error code",
      "message":"message text",
      "description":"error description"
    }
}

API Version History

You can find the documentation for older API versions following the links below.

API version Released Status
v1 Release 7 2018-10-15 Online & Supported
v1 Release 6 2018-05-25 Online & Supported
v1 Release 5 2017-05-04 Online & Supported
v1 Release 4 2017-10-13 Online & Supported