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