Real Time Bus Data

The Bus CIS Service accepts real-time data from buses via TCIP-JSON which is denoted below. Note that, as the comments indicate, the example below is not actually valid JSON due to the comments.

TCIP is a large and complex standard, only a portion of which is implemented below. TCIP is described here. Technically TCIP is typically seen in XML format, but the next release of TCIP is making allowances for JSON as well.

// Real-time MTA Bus CIS Interface Specification (Draft)
// Interface between Bus Hardware Subsystem (BHS) and Bus CIS Server (BCS)
// The interchange format for this interface is JSON (http://json.org)
// The data model/specification for the content is APTA's TCIP (http://aptatcip.com/)
// -----------------------------------------------------------------------------------
// This file is not actual valid JSON, because JSON doesn't allow for comments -- remove
// all of the lines starting with '//' and the result will be valid JSON.
// It should be noted that there are still details to be worked out. For example,
// the circumstances under which some of these fields will be left out given data availability.
//
// In practice, all unnecessary whitespace should be removed when creating messages to be sent
// over the air, including indentations, newlines, and space between punctuation.
{
  // The "root" element, specifying that it's a CcLocationReport per the APTA TCIP standard
  "CcLocationReport": {

    // the "request ID" -- just an incremental counter starting at 1 when the terminal powers up
    "request-id": 1205,

    "vehicle": {
      // The numeric portion of the vehicle ID
      "vehicle-id": 7560,

      // A numeric APTA-defined identifier for MTA NYCT
      "agency-id": 2008,

      // A text-based identifier for same.
      "agencydesignator": "MTA NYCT"
    },

    // TCIP-required field. Hardcode as zero for now
    "status-info": 0,

    // Timestamp of the on-board device when this message is created, in standard XML timestamp format
    "time-reported": "2011-06-22T10:58:10.0-00:00",

    // Latitude, in microdegrees, taken from GPS data
    "latitude": 40640760,

    // Longitude, in microdegrees, taken from GPS data
    "longitude": -74018234,

    "direction": {
      // Instantaneous direction of travel, in decimal degrees, taken from NMEA RMC sentence
      "deg": 128.77
    },

    // Instantaneous speed. Per SAE J1587 speed is in half mph increments with an offset of -15mph.
    // For example, 002.642 knots (from RMC) is 3.04 mph, so (15*2) + (3 * 2) = 36
    // Valid range is [0,255], which equates to [-15mph, +112.5mph]
    "speed": 36,

    // An optional indicator for the "quality" of the location/speed data. 4 signifies data not available
    // Only use this field when GPS/NMEA data are not available, and in that case value is always 4
    "data-quality": 4,

    // The "Terminal ID" with some prefix we have assigned, e.g. VFTP (for VeriFone TransitPay)
    "manufacturer-data": "VFTP123456789",

    // The operator's pass number, from the IFU
    "operatorID": {
      // Hard coded as zero, because it is a required field
      "operator-id": 0,

      // As a string. For now, indentical, but future login device could have characters too.
      "designator": "123456"
    },

    // The operator's run information, from the IFU
    "runID": {
      // Hard coded as zero, because it is a required field
      "run-id": 0,

      // the "run number", from the IFU communications,
      "designator": "1"
    },

    // Numeric value of the DSC
    "destSignCode": 4631,

    // Exactly as is, but only when the emergency message flag is set. Otherwise, leave out
    "emergencyCodes": {
      "emergencyCode": [
        "1"
      ]
    },

    "routeID": {
      // Hard coded as zero, because it is a required field
      "route-id": 0,

      // ASCII of the "run route", from the IFU communications.
      "route-designator": "63"
    },

    // Local TCIP extension for NMEA sentences. Include only if the GGA and RMC are present.
    "localCcLocationReport": {
      "NMEA": {
        "sentence": [
          // The most recent NMEA RMC sentence
          "$GPRMC,105850.00,A,4038.445646,N,07401.094043,W,002.642,128.77,220611,,,A*7C",

          // The most recent NMEA GGA sentence
          "$GPGGA,105850.000,4038.44565,N,07401.09404,W,1,09,01.7,+00042.0,M,,M,,*49"
        ]
      }
    }
  }
}