Attachment C TPIMS Truck Parking Data Interface.pdf

Version 2.0

Specification Document for Truck Parking Data Exchange

Revision History. The following revision table presents the changes made for each version of this document.

Revision Date State/Description

1.0 February 2017 Creation based on the MAASTO TPIMS

XML Data Feed memorandum from September 18th 2016

1.1 April 2017 Added time zone field to the static feed and

clarified the highway nomenclature

1.2 July 2017 Proposed changes from MAASTO TPIMS

Workshop #5

1.3 August 2017 Proposed changes from the Partnership states.

1.3.1 August 2017 Capacity added to the dynamic and archive

only feeds samples.

1.3.2 October 2017 Modification of the verification checks format and clarification on time zone.

2.0 November 2017 Added TPIMS API Guidance.

Table of Contents

Overview This document summarizes the standard data feeds that each state will provide for their publicly and privately owned (as applicable) truck parking sites. The Application Programming Interface (API) guidance provides a recommended approach for implementing the webservices that will facilitate the sharing of truck parking availability data with other users. The data elements and formatting were agreed upon by the eight states participating in the MAASTO TPIMS project, and are intended to set a standard for future projects.

There are three separate data feeds, each with their own function. The data feeds include a dynamic public feed, static public feed, and dynamic archive only feed. The dynamic and static public feeds are meant to be shared with third party application developers and other agencies to allow them to disseminate the truck parking availability information through their applications. The dynamic archive only feed is meant for internal system monitoring and performance measure generation.

Specification Document for Truck Parking Data Exchange

Application Programming Interface (API) Guidance Recommendations for the Application Programming Interface (API), which will allow trusted partners and third-party developers to access TPIMS data, are provided in this section. The TPIMS API should follow HTTP RESTful conventions (REpresentational State Transfer). Recommended sets of HyperText Transfer Protocol (HTTP) request messages are provided, along with a definition of the structure of response messages in JavaScript Object Notation (JSON) format.

The intended RESTful API is stateless, meaning that request authentication does not depend on cookies or sessions. Instead, each request must pass authentication credentials. MAASTO Partnership states may choose to enable authentication on their dynamic public feed and static public feed or keep them open.

All dynamic archive only feeds need to be restricted to authenticated users (trusted partners). Trusted Partners include MAFC, State DOTs, and other users individually approved by each DOT. It is recommended to use API tokens for authentication, with each user having a unique key. A token/key is represented in the below examples as “MyKey”.

Users should be able to access each state’s TPIMS API by client browser plugin, cURL or HTTP library.

It is recommended the access methods provided by the REST APIs are limited to GET. There are three separate data sets, each with their own function. The data feeds include a dynamic public feed (dataset #1), static public feed (dataset #2), and dynamic archive only feed (dataset #3). See the data definition section for more information on the contents of these data sets.

Dataset/Datafeed Requests:

1) Request availability and location information for all truck parking sites (Third Party Requests):

• Dynamic Public Feed Database – Dataset #1

• Static Public Feed Database – Dataset #2 (Updated As-Needed)

2) Request most recent archive feed (Only Trusted Partners):

• Dynamic Archive Only Feed Database – Dataset #3

Specification Document for Truck Parking Data Exchange

Sample Call Datafeeds with Recommended Formats:

1) Request availability and location information for all truck parking sites (Dynamic & Static Public Feeds):

• Dynamic Public Feed Database – Dataset #1:

Call Request Open Feed:

GET /api/TPIMS_Dynamic.json

Call Request Restricted to Authenticated Users Feed:

GET /api/TPIMS_Dynamic?key=<MyKey>

Response:

[{"siteId":"MI00039IS0011300SRSTARE11","timeStamp":"2017-11-17T20:39:59Z","timeStampStatic":"2016-12- 02T16:23:22Z","reportedAvailable":"49","trend":"FILLING","open":true,"trustData":true,"capacity":68}]

• Static Public Feed Database – Dataset #2 (Updated As-Needed):

Call Request Open Feed:

GET /api/TPIMS_Static.json

GET /api/TPIMS_Static?key=<MyKey>

Response:

[{"siteID":"MI00039IS0011300SRSTARE11”,"timeStamp":"2017-07- 16T18:26:16Z","relevantHighway":"94","referencePost":”106”,"exitID":null,"directionOfTravel":"S","name":"Rest Area #11","location":{"latitude":43.428567,"longitude":-89.483269,"streetAdr":null,"city":”Johnson County”,"state":"MI","zip":”12345”,"timeZone":"Eastern"},"ownership":"PU","capacity":68,"amenities":[],"images":[],"log os":[]}]

2) Request Most Recent Archive Feed (Only Trusted Partners):

• Dynamic Archive Only Feed Database – Dataset #3:

GET /api/TPIMS_Archive?key=<MyKey>

Response:

[{"siteId":"MII00039IS0011300SRSTARE11","timeStamp":"2017-11-17T21:48:32Z","timeStampStatic":"2016-12- 02T16:23:22Z","reportedAvailable":"55","trend":"FILLING","open":true,"trustData":true,"lastVerificationCheck":"2016-12- 02T16:23:22Z",”verificationCheckAmplitude”:-3,"lowThreshold":5,"trueAvailable":55,"capacity":68}]

Specification Document for Truck Parking Data Exchange

Dynamic Public Feed The dynamic public feed contains eight data fields, which are updated every one to five minutes. They are located in this category because the information contained in the data elements needs to be updated frequently in order to provide accurate data to the user. The fields in the dynamic public feed are as follows:

JSON

Element Type Description siteId string

Unique fixed-length identifier including state, route number, route type, reference post, side of road and unique location number or name abbreviation. See more detailed description in appendix.

timeStamp string Provides the date and time that the site record was last updated. See more detailed date and time representation description in appendix.

timeStampStatic string Provides the date and time that the site static record was last updated. See more detailed date and time representation description in appendix.

reportedAvailable string

Number of available spots shared through the data feed. The number is capped at the total number of parking spots at the site and “Low” is reported if the low threshold is reached.

trend string

Optional. Reports whether the site is emptying, steady or filling. Accepted values: “CLEARING” / “STEADY” / “FILLING” / null. See more detailed description in appendix.

open boolean Will report open unless the parking site is closed to parking for maintenance or another situation.

Possible values: true / false / null trustData boolean

This flag will report that the site is operating normally.

Possible reasons for a “false” value include periods where the site is under construction while open to traffic, IT maintenance windows, or equipment failures. Possible values: true / false / null capacity number Total number of parking spots within the site.

Specification Document for Truck Parking Data Exchange

Dynamic Public Feed - example

JSON format [{"siteId":"WI00094IS0012400ERSTARE53","timeStamp":"2016-08-15T20:35:15Z","timeStampStatic":"2015-05 03T12:24:19Z","reportedAvailable":"25","trend":"FILLING","open":true,"trustData":true,"capacity":41}]

Dynamic Public Feed - live URL https://transportal.cee.wisc.edu/TPIMS/dynamic

Static Public Feed The static public feed contains 19 data fields, which are updated on an as-needed basis. They are located in this category because the information is not expected to change very often. This allows for more efficient use of bandwidth since the information in the static public data feed only needs to be pulled one time after a change is made. As presented above, the dynamic feed contains a timestamp of when the static feed was last updated. The fields in the static public data feed are as follows:

JSON

Element Type Description siteId string

Unique fixed-length identifier including state, route number, route type, reference post, side of road and unique location number or name abbreviation. See more detailed description in appendix.

timeStamp string Provides the date and time that the site record was last updated. See more detailed date and time representation description in appendix.

relevantHighway string Provides the highway from which the rest area can be accessed. See highway nomenclature in appendix.

referencePost string Provides the Reference Post (mile marker) for the center of the rest area or interchange.

exitID string

At interchanges, the designated interchange number is provided. For rest areas and weigh stations that do not have an exit identification the value will be set to null.

directionOfTravel string Text indicating the direction(s) of travel that can access the site. For sites that can be accessed by

Specification Document for Truck Parking Data Exchange either direction of travel, a bidirectional identifier such as “NS” or “EW” can be used.

name string Name of facility as text (e.g., Rest Area or Flying J Truck Stop).

location array This array contains the seven following data elements about the site’s physical location:

latitude number The latitude in a float format.

longitude number The longitude in a float format.

streetAdr string Text based address number and street name.

city string Name of city in which the parking area is located. If not in a city, the county name can be used (e.g., Johnson County).

state string Abbreviation for state in which the parking area is located.

zip string ZIP code of the location timeZone string Time zone in which parking is located. Accepted values: “Eastern” / “Central” / “Mountain” / “Pacific” / “Alaska” ownership string Text used to indicate whether a parking site is privately owned or publicly owned. Accepted values:

“PR” / “PU”

capacity number Total number of parking spots within the site.

amenities array of strings

Optional. List of text based amenities descriptions.

Data structure would allow a varying number of amenities to be listed.

images array of strings

Optional. Provides a link to an image file on a server that shows the lot status visually. This is only used if images are being captured and shared from a surveillance camera, otherwise it will be null.

logos array of strings

Optional. Provides a link to an image file on a server that shows the private truck stop logo or TPIMS logo.

Specification Document for Truck Parking Data Exchange

Static Public Feed - example

JSON format [{"siteId":"WI00094IS0012400ERSTARE53","timeStamp":"2016-08-15T20:35:15Z", "relevantHighway":"I94”,"referencePost":"123","exitID":"24","directionOfTravel":"0E","name":"House of the happy trucker","location":{"latitude":43.0000, "longitude":-89.0000, "streetAdr":"34 State Street","city":"Madison","state":"WI","ZIP":"53703","timeZone":"Central" },"ownership":"PU","capacity":25,"amenities":

["Shop", "Showers", "ATMs"],"images": [ "http://.../image1.jpg","http://.../image2.jpg","http://.../image3.jpg"],"logos": [ "http://.../logo1.jpg","http://.../image2.jpg"]}]

Static Feed - live URL https://transportal.cee.wisc.edu/TPIMS/static

Dynamic Archive Only Feed The dynamic archive only feed will be sent to MAFC for performance tracking and can be used internally for each state. The first eight data fields are the same as those in the dynamic public feed, and the last five are additional fields for use for performance measures. The fields will be updated every one to five minutes like the dynamic public data fields. The fields in the dynamic archive only data feed are as follows:

Element Type Description siteId string

Unique fixed-length identifier including state, route number, route type, reference post, side of road and unique location number or name abbreviation. See more detailed description in appendix.

timeStamp string Provides the date and time that the site record was last updated. See more detailed date and time representation description in appendix.

timeStampStatic string Provides the date and time that the site static record was last updated. See more detailed date and time representation description in appendix.

reportedAvailable string

Number of available spots shared through the data feed. The number is capped at the total number of parking spots at the site and “Low” is reported if the low threshold is reached.

trend string

Optional. Reports whether the site is emptying, steady or filling. Accepted values: “CLEARING” / “STEADY” / “FILLING” / null. See more detailed description in appendix.

Specification Document for Truck Parking Data Exchange open boolean Will report open unless the parking site is closed to parking for maintenance or another situation. Possible values: true / false / null trustData boolean

This flag will report that the site is operating normally.

Possible reasons for a “false” value include periods where the site is under construction while open to traffic, IT maintenance windows, or equipment failures.

Possible values: true / false / null capacity number Total number of parking spots within the site.

lastVerificationCheck string

Date and time of the last manual reset/verification check. Used for performance measures and system monitoring, not for public consumption. Possible values: date and time / null. Null is input if a state is manually providing verification check data to MAFC.

See more detailed date and time representation description in appendix.

verificationCheckAmplitude number Amplitude of the last manual reset/verification check adjustment. Can be negative, positive or zero.

lowThreshold number If the parking spot availability in the lot drops below this value, the data feed will report “Low” instead of a number.

trueAvailable number

This will be the actual number of spots the detection system is reporting is available. This number can exceed the maximum number of spots and will report actual values under the “Low” threshold or even negative values. Used for performance measures and system monitoring, not for public consumption.

Dynamic Archive Only Feed - example JSON format [{"siteId":"WI00094IS0012400ERSTARE53","timeStamp":"2016-08- 15T20:35:15Z","timeStampStatic":"2015-05- 03T12:24:19Z","reportedAvailable":"12","trend":”FILLING","open":true,"trustData":tr ue,"lastVerificationCheck":"2016-08-15T20:35:15Z","verificationCheckAmplitude ":- 2,"lowThreshold":5,"trueAvailable":12,"capacity":41}]

Dynamic Archive Only Feed - live URL https://transportal.cee.wisc.edu/TPIMS/archive

Specification Document for Truck Parking Data Exchange

Appendix

Location Identifier

Location Identifier (Fixed Length) Field

Position

Field Size Field Name Description

number Five digits with zeros padded to the left.

9 6 Reference Post

17 8 Unique Site Designation

Example: MI00094IS0008450WGALESBRA is the Galesburg Rest Area on westbound I- 94 in Michigan near reference post 84.5.

Date and Time Representation

The timestamp follows the standard ISO 8601 extended format and is represented in UTC with a combined date and time representation. Therefore, the date will read yyyy-mm-ddThh:mm:ssZ where:

• yyyy: Four-digit year

• mm: Two-digit month

• dd: Two-digit day

• ‘T’: marker for Time

• hh: Two-digit hour expressed in 24-hour time

• mm: Two-digit minute

• ss: Two-digit second

• ‘Z’: represents “Zulu time”, which is the zone designator for zero UTC offset.

Specification Document for Truck Parking Data Exchange

The static data feed contains the time zone where the rest area is located for ease of interpretation by the data consumer.

Highway Nomenclature

Following the MAASTO data standard, the highway nomenclature uses the number, followed by “IS” if it’s an interstate, “US” if it is a US highway or “SH” if it is a state highway. The order to be used for concurrent highways is Interstate Highways, U.S. Highways, state highways, and finally county roads, and within each class by increasing numerical value.

Trending Calculation The trend calculation is optional, and is intended to provide more information about the current state of available parking. The thresholds for FILLING and CLEARING should be user adjustable, as individual sites may operate uniquely and require independent adjustments.

The trending state is based on calculating vehicle flow over the past 30 minutes. For each reporting cycle the difference (delta) in availability is divided by capacity to determine a delta percentage. Flow is then calculated by summing the delta percentages over the past 30 minutes. For a system with 5-minute reporting cycles:

Delta and Flow Calculation %Deltan = Availability Delta, expressed as a percentage, where “n” marks the elapsed time since the measured interval in minutes.

%Deltan = [ (Availabilityn – Availabilityn-5) / Capacity ]

%Delta0 = Truck Parking Availability Delta % between now and 5 minutes ago (most recent data point) %Delta5 = Truck Parking Availability Delta % between 5 minutes ago and 10 minutes ago %Delta10 = Truck Parking Availability Delta % between 10 minutes ago and 15 minutes ago %Delta15 = Truck Parking Availability Delta % between 15 minutes ago and 20 minutes ago %Delta20 = Truck Parking Availability Delta % between 20 minutes ago and 25 minutes ago %Delta25 = Truck Parking Availability Delta % between 25 minutes ago and 30 minutes ago

%Flow = %Delta0 + %Delta5 + %Delta10 + %Delta15 + %Delta20 + %Delta25

Thresholds Threshold for the trend states are based on the %Flow calculation. It is recommended that these are adjustable per site, and that each site is observed during the burn-in period to adjust if too much “bouncing” between trending states is occurring. Expressed in terms of %Flow, the recommended defaults are:

“Clearing”: Flow > 4.5% “Steady”: -4.5% < Flow < 4.5%

Specification Document for Truck Parking Data Exchange

“Filling”: Flow < -4.5%

Example

The below table shows 35 reporting cycles of data, every five minutes, for a facility with a capacity of 50 vehicles:

Time Availability Delta % Delta %Flow Flow State

12:15 9 -1 -2.0%

12:20 8 -1 -2.0%

12:25 8 0 0.0%

Specification Document for Truck Parking Data Exchange

As shown in the table, %Delta is computed beginning with the 2nd reporting cycle. The first %Flow calculation starts with the 7th reporting cycle, utilizing and 5 most recent %Delta values.

For the 12:30 reporting cycle:

%Flow = %Delta12:30 + %Delta12:25 + %Delta12:20 + %Delta12:15 + %Delta12:10 + %Delta12:05 = 2.0% + 0.0% - 2.0% - 2.0% - 16.0% - 4.0%

= -22.0% (Filling)

For the 13:55 reporting cycle:

%Flow = %Delta13:55 + %Delta13:50 + %Delta13:45 + %Delta13:40 + %Delta13:35 + %Delta13:30 = -2.0% + 2.0% + 4.0% + 4.0% + 2.0% + 0.0%

= 10.0% (Clearing)