IRMA onAir logo

Getting Started

Please note this API documentation is not about the latest API, but it is still supported. For working with the latest API please visit the main documentation page.

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.4

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

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 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/r4/stops/demo?vehicleId=demo&opdate=2017-04-04"

Response Codes

Code Name Description
200 OK Success
401 Unauthorized Client did not provide basic authentication
403 Forbidden Invalid combination of username and password
404 Not Found Invalid API resource or invalid request

All errors will return JSON in the following format:

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

Release Notes

Change Status Description
Stop Matching New Feature Export of Stop identifiers to the field id of a Stop Record, if stop matching is enabled in the context of the APC project. If stop matching is not supported, the field id is not available within the document in order to reduce network traffic.
Door Opening Times New Feature Introduction of Door Opening Times on a vehicle basis. If configured in the context of the current APC project, those APC events are summarized that were recorded at the same time and share the same geolocation.
The door opening time is the timestamp of the first door opened during a stop and exported to field timeStart of a Stop Record. The door closing time reflects the closing of the last door and exported to field timeStop.
If calculation of Door Opening Times is activated, several APC events are summarized which means the data is not pure raw data anymore. If not activated, the fields timeStart and timeStop contain the same timestamp, which shows when that APC event was recorded.
Excel Report Minor Change The underlying pattern for showing dates and timestamps was added. It is bound to the locale settings of the user account. The pattern information is placed in the header of the report. Example for German date pattern: dd.MM.yy.

/stops/{operator}/

The stops/{operator}/ resource returns a set of counting data records in descending order. Operation date and vehicle identifier serve as mandatory input parameters.

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/r4/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 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

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
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"``

curl -u user:pwd -k -X POST -H "Accept: application/json" "https://api.irmaonair.com/services/REST/apc/v1/r4/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",
         "deviceId":"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"
            }
         ]
      }
   }
}

/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 record including 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/r4/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

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.

curl -u user:pwd -k -X POST -H "Accept: application/json" "https://api.irmaonair.com/services/REST/apc/v1/r4/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/r4/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.

curl -u user:pwd -k -X POST -H "Accept: application/json" "https://api.irmaonair.com/services/REST/apc/v1/r4/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":"demo",
         "shortName":"demo",
         "longName":"demo",
         "email":"irmaonair@irisgmbh.de",
         "language":"en-US",
         "timeZone":"UTC",
         "devices":{
            "serialnumber":"364950",
            "vehicleid":"demo"
         }
      }
   }
}

/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/r4/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/r4/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"

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.

{
   "VDV457":{
      "timestamp":"2017-10-13T12:50:19Z",
      "version":"0.1",
      "VEHICLE":{
         "operator":"demo",
         "deviceId":"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-01-22T14:17:12Z</timestamp>
  <version>0.1</version>
  <VEHICLE>
    <operator>demo</operator>
    <deviceId>demo</deviceId>
    <time>2018-01-22T14:17:12Z</time>
    <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>
      <apc>
        <door>1</door>
        <catId>0</catId>
        <in>4</in>
        <out>4</out>
      </apc>
    </stop>
  </VEHICLE>
</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

Document Header

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

Field Comment Example
timestamp Timestamp of document created 2016-12-01T09:51:17+02:00
version Identifier for current data interface version 0.1

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

The first line of CSV documents contains the document header.

{
  "VDV457":{
      "timestamp":"2018-01-22T14:10:40Z",
      "version":"0.1"
  [...]
  }
}
<VDV457>
    <timestamp>2018-01-22T14:17:12Z</timestamp>
    <version>0.1</version>
    [...]
</VDV457>
2018-01-22T13:01:07Z;0.1

Vehicle Header

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 Comment Example
operator Short name of the operator as specified during project setup demo-operator
deviceId The identifier of the vehicle as specified during project setup. If not specified, IRMA Hub device Id is returned. demo-bus
time Timestamp of record created 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.

{    
  "VEHICLE":{
  "operator":"demo",
  "deviceId":"demo",
  "time":"2017-10-13T12:50:19Z"
  [...]
  }
}
<VEHICLE>
  <operator>demo</operator>
  <deviceId>demo</deviceId>
  <time>2018-01-22T14:17:12Z</time>
  [...]
</VEHICLE>
VEHICLE;demo;demo-bus;2018-01-22T13:01:07Z

Stop Record

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 Comment Example
type Actual stop detected = 1 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. StopABC123
timeStart Time of earliest door opening event as timestamp including time zone. 2016-01-01T01:01:01+02:00
timeStop Time of latest door opening event as timestamp including time zone. 2016-01-01T01:02:01+02:00
lon GPS x-coordinate (longitude) of the stop. Coordinates are represented in WGS84 decimal format. 14.0995958
lat GPS y-coordinate (latitude) of the stop. Coordinates are represented in WGS84 decimal format. 51.0466250

APC record

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 Comment Example
door Unique door number within a vehicle, door numbers will be incremented starting from 1 (1..n) 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 0
in Number of Boardings 10
out Number of Alightings 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.

{
  "stop":[{
    "type":"1",
    "id":"Stop123ABC",
    "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"
    }
  }]
}
<stop>
  <type>1</type>
  <id>Stop123ABC</id>
  <timeStart>2017-06-01T19:10:15Z</timeStart>
  <timeStop>2017-06-01T19:10:15Z</timeStop>
  <lon>14.0995958</lon>
  <lat>51.0466250</lat>
  <apc>
    <door>1</door>
    <catId>0</catId>
    <in>4</in>
    <out>4</out>
  </apc>
</stop>
1;Stop123ABC;2017-06-01T19:10:15Z;2017-06-01T19:10:15Z;14.0995958;51.0466250;1;0;4;4