GSI - TNC Data Exchange

Document Type: Interface Spec

Authors: Jon Finley
Date: 05/07/2017

1301 Corporate Center Drive Suite 170

Eagan, MN 55121
www.gksys.com

Document Summary: This document describes the functionality available to accept data from a
Transportation Network Company (TNC). Version 4 – includes shared_ride and party_count.

GateKeeper Systems Confidential Page 1 of 5

Copyright © 2017 GateKeeper Systems Inc. All rights reserved. This document is intended for use by GateKeeper Systems, Inc. employees and designated affiliates. Do not reproduce or
distribute this document in any way, shape, or form without prior permission from an authorized company representative.
 Table of Contents
TABLE OF CONTENTS ..........................................................................................................................2
1 OVERVIEW .......................................................................................................................................... 3
2 DESCRIPTION ....................................................................................................................................... 3
3 CUSTOMER SPECIFIC DATA ..................................................................................................................... 3
4 IMPLEMENTATION ................................................................................................................................ 3
4.1 Message Details .......................................................................................................................... 3
4.1.1 Sample JSON Data Packet ................................................................................................... 3
4.1.2 Sample Request Header...................................................................................................... 4
4.1.3 Authentication .................................................................................................................... 4
4.1.4 JSON Message Fields........................................................................................................... 4
4.1.5 Response ............................................................................................................................. 5

GateKeeper Systems Confidential Page 2 of 5

Copyright © 2017 GateKeeper Systems Inc. All rights reserved. This document is intended for use by GateKeeper Systems, Inc. employees and designated affiliates. Do not reproduce or
distribute this document in any way, shape, or form without prior permission from an authorized company representative.
1 Overview
The purpose of the functionality is to provide the means for any TNC to send an entry, exit, and
pickup or dropoff event to the Airport’s Ground Transportation Management System when a TNC
vehicle accesses the facility. This data is then recorded with all other ground transportation data
allowing the site to charge, report, and audit information as desired.

2 Description
Geofence Identifier (geofence_id) maps to a particular geofence at a particular facility.
Transaction Type (txn_type - see below) maps to a Read Point.
TNC Identifier (tnc_id) maps to an Account.

A message received for a Driver that does not exist in the system causes a new record to be
created using the uid value for the Traveler ReferenceNumber and license_plate value for the
Vehicle ID.

3 Customer Specific Data

Each customer has their own implementation of the system (and database). All messages being
generated for this customer will be sent to a URL specific to that entity. An entity may have several
sites or facilities (reliever airports). Thus; all messages for entity A are to be sent to URL 1, all
messages for entity B are to be sent to URL 2, and so forth.

Several values are unknown until implementation and will be assigned at that time. These include:
a. URL
b. tnc_id
c. username and password
d. geofence_id

4 Implementation
The data exchange is accomplished using an HTTP/HTTPS POST message which contains a JSON
data packet. The HTTP result codes are listed below. A response other than 200 indicates that the
message was not received and should be resent.

4.1 Message Details

The HTTP/HTTPS request body is defined as follows.
4.1.1 Sample JSON Data Packet
{"uid": "62268341a", "timestamp": "2015-03-24T16:29:29Z", "lon": -122.39938,
"license_plate": "7EOY869", "ride_count": 1, "tnc_id": 32513, "lat":
37.6327, "txn_type": "ENTRY", "geofence_id": "ABC123", "shared_ride": "1",
"party_count": "2"}

*Note: The quotation marks used in the message must be the ASCII 034 character
and not left or right quotation marks, which Microsoft Word can insert
automatically.

GateKeeper Systems Confidential Page 3 of 5

Copyright © 2017 GateKeeper Systems Inc. All rights reserved. This document is intended for use by GateKeeper Systems, Inc. employees and designated affiliates. Do not reproduce or
distribute this document in any way, shape, or form without prior permission from an authorized company representative.
 4.1.2 Sample Request Header
POST / HTTPS/1.1
Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Length: 208

4.1.3 Authentication
The username and password contained in the request header follow the HTTP
standards of the two values separated by a colon and Base64 encoded. This
credential will vary from customer to customer.
4.1.4 JSON Message Fields
uid
Driver Id
Driver Id is the unique identifier for a Driver.

Format: String (alphanumeric (A-Za-z0-9) and dash/hyphen (-))

Example Value: 3c22a7453

tnc_id
The assigned number for the TNC. This value may be the same across all airports for
a specific TNC (or it may vary).

Format: Format: String (integer – 0-9)

Example Value: 32123

license_plate
Vehicle license plate value. Cannot be blank.

Format: String (alphanumeric (A-Za-z0-9), dash, and asterisk)

Example Value: 7ABC529

timestamp
The time the event occurred.

Format: ISO 8601 Date and Time in UTC using a 24 hour clock,
[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]Z
Example Value: 2015-02-06T14:58:27Z

txn_type
The type of event specific to the geofence that is referenced in this message.

Format: String
Possible Values: ‘ENTRY’, ‘EXIT’, ‘PICK-UP’, ‘DROP-OFF’

ride_count
Indicates whether a passenger is in the vehicle (1) or not in
the vehicle (0).

GateKeeper Systems Confidential Page 4 of 5

Copyright © 2017 GateKeeper Systems Inc. All rights reserved. This document is intended for use by GateKeeper Systems, Inc. employees and designated affiliates. Do not reproduce or
distribute this document in any way, shape, or form without prior permission from an authorized company representative.
 Format: Format: String (boolean – 0 or 1)
Possible Values: 0 or 1

lon
The longitude coordinate of the event.

Format: World Geodetic System 1984 (WGS84)

Example Value: -122.4129622

lat
The latitude coordinate of the event.

Format: World Geodetic System 1984 (WGS84)

Example Value: 37.7603668

geofence_id
Geofence Id
A unique identifier for each geofence at the facility/airport. i.e. One customer (Clark
County Department of Aviation) may have several sites (McCarran, Overton, Jean,
etc.) and each site may have more than one geofence (McCarran Taxi Staging,
McCarran Terminal 1, etc.). The value identifying each geofence will be agreed
upon at time of implementation.

Format: String (alphanumeric – A-Za-z0-9)

Example Value: 3c22a7453

shared_ride
Indicates whether the TNC Operator is on shared trip. That is, carrying multiple
paying fares (“parties”) that have agreed to ride together to decrease their cost.

Format: String (boolean – 0 or 1)

Possible Values: 0 or 1

party_count
Indicates the number of parties that are currently in the vehicle. This is NOT the
same as the number of passengers. Each party counts as 1.

Format: String (integer – 0-9)

Example value: 2

4.1.5 Response
HTTP 200: Returned for a valid message that was successfully processed.
HTTP 401: Returned for a message with an incorrect username/password.
HTTP 400: Returned for a failed message. Either not received or there was a
processing error.
All messages that do not receive an HTTP 200 should be buffered (error corrected, if
necessary) and transmission retried until an HTTP 200 is received.
GateKeeper Systems Confidential Page 5 of 5

Copyright © 2017 GateKeeper Systems Inc. All rights reserved. This document is intended for use by GateKeeper Systems, Inc. employees and designated affiliates. Do not reproduce or
distribute this document in any way, shape, or form without prior permission from an authorized company representative.