FTP Developer Guide for GPS Toll Verification

Intended Audience

Developers who want to upload GPS data for tolls verification using PrePass GPS Tolls FTP solution.

Alternately, carriers may leverage the PrePass GPS Tolls API to share their GPS data via API.

Access

Access may be obtained from your account manager, or through PrePass customer service.

Connection

  1. Connect to ftp.prepass.com with the credentials provided by PrePass.

  2. Your default FTP folder will be your PrePass account number.

If the folder name does not match your account number, please notify your account manager or PrePass customer service.

Figure 1 - Logged in view of ftp client.

Tolls GPS CSV File Format and Data Contracts

You may generate a GPS data file for one or multiple vehicles.

FTP file and filename format: tolls_gps_<*unique*>.csv

Your GPS data file name should conform to the above naming convention. The file name may contain designations specific to your organization, but the filename has to

  1. Begin with “tolls_gps_”

  2. Contain a unique alpha-numeric identifier that you set, such as account number, date and vehicle information, and

  3. End with a .csv file type.

File format is comma separated values, or csv.

GPS Data CSV Row Format

Field Name
Example
Required
Description

DeviceNumber

06XXXXX73

Required if VIN not present 

It can be either the transponder Id or the Mobile device Id assigned to the account

VIN

1X**D*&67D*8****7

(17 digit Valid VIN)

Required if Device Number not present 

Vehicle Identification Number

PlateNumber 

JD*8*P

Optional 

Vehicle plate number

PlateState 

CA

Optional 

State abbreviation

TotalAxleCount 

4

Optional 

Latitude 

[-90, 90]

i.e.: 30.213333

Required 

The latitude of the geographical coordinate.

Longitude 

[-180, 180]

-112.23232

Required 

The longitude of the geographical coordinate.

Timestamp 

Epoch

i.e.: 1687979999

Required 

The epoch time (or Unix time) is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT)

Timezone 

i.e.:  -14400

Required 

Speed

[0,60]

i.e.: 25.9

Optional 

The instantaneous speed of the device, measured in meters per second.

DirectionOfTravel 

[0,180] *depends on platform.

i.e.: 360

90

Optional 

The direction in which the device is traveling, measured in degrees and relative to due north.

GpsLocationAccuracy 

*Meters or Percentage?

5.23

Optional 

The accuracy of a geographical coordinate, measured in meters. *We recommend using signals with no more than a 20m radius for the best results.

Example CSV - Single Vehicle

DeviceNumber, Vin, PlateNumber, PlateState, TotalAxleCount, Latitude, Longitude, Timestamp, Timezone, Speed, DirectionOfTravel, GpsLocationAccuracy

06XXXXX7,1X**D*&67D*8****7,J*5*HP,CA,4,30.213333,-112.23232,1687979999,-14400,25.9,37.99,5.23

Example CSV - Multiple Vehicles

DeviceNumber, Vin, PlateNumber, PlateState, TotalAxleCount, Latitude, Longitude, Timestamp, Timezone,Speed, DirectionOfTravel, GpsLocationAccuracy

06XXXXX7,1X**D*A67D*8****7,J*5*HP,CA,4,30.213333,-112.23232,1687979999,-14400,25.9,37.99,5.23

07XXXXX2,1P**D*B21D*8****7,K*6*FA,CA,4,30.213333,-111.23232,1687979999,-14400,25.9,37.99,5.23

Transfer GPS CSV File Using FTP Client

Once Tolls GPS data files are ready, the next step is to upload for processing.

FTP File Upload

Figure 2 - Upload tolls GPS csv file to specific ftp location.

Figure 2 - Upload tolls GPS CSV file to specific FTP location.

FTP File Processor

The FTP File processor will process all uploaded GPS data files.

Output of FTP file processor can be success or failure as outlined below.

FTP Success

A successfully processed input file will be removed from the folder location and a success status file will be generated for each respective input file.

File Name: success-<original file name>-<processing date>.txt

Content: Successfully processed vehicle GPS data.

Figure 3 - Successful status file

FTP Failure

If input validations fail within a given input file, that file will be removed from the input folder and placed in the “Rejected” folder.

Figure 4 - Rejected folder.

Figure 4 - Original GPS data file moved to Rejected folder.

There will also be a corresponding failure status file placed in the “Rejected” folder, which will contain further information about the specific processing errors in the input file.

Figure 5 Failed status file.

File Name: processingerror_<original file name>_<processing date>.csv

Content: CSV file with

Heading
Heading

ErrorLineNumber

Line number of original csv file

ErrorMsg

Error message for specific fields which are invalid.

Figure 6 Processing error file contents