AVLListener

  • 15.5
This article is may not be up to date with the latest stable release of M4.

Description

The AVLListener endpoint provides the API consumer with access to methods pertaining to tracking real-time truck location data. The methods allow consumers to pull and post data regarding GPS locations.

Methods

URL base/GPS/AVLListener/Specification
Action GET
Description Returns a data dictionary that details the available web service methods related to the AVLListener controller.
Parameters None
Returns  A JSON object with method descriptions
Sample Return Object 
[
  {
    "HttpAction": "Post",
    "MethodName": "SubmitAVL",
    "Description": "The SubmitAVL method takes a single AVL Entry record using the specified format. Any additional fields that are not a part of the specified JSON spec will be stored as additional package data in the database.",
    "Format": {
      "DeviceID": "DeviceID as specified in Truck list",
      "Latitude": 12.333,
      "Longitude": -22.123,
      "TruckName": "Sample Truck Name",
      "ESN": "Sample ESN",
      "Speed": 55.4,
      "Bearing": 47.38,
      "FixTime": "2018-03-12T19:22:02.2191606-04:00"
    }
  },
  {
    "HttpAction": "Post",
    "MethodName": "SubmitAVLGroup",
    "Description": "The SubmitAVLGroup method takes a list of AVL Entry records using the specified format. Any additional fields that are not a part of the specified JSON spec for an individual AVL entry will be stored as additional package data in the database.",
    "Format": [
      {
        "DeviceID": "DeviceID as specified in Truck list",
        "Latitude": 12.333,
        "Longitude": -22.123,
        "TruckName": "Sample Truck Name",
        "ESN": "Sample ESN",
        "Speed": 55.4,
        "Bearing": 47.38,
        "FixTime": "2018-03-12T19:22:02.2191606-04:00"
      },
      {
        "DeviceID": "DeviceID as specified in Truck list",
        "Latitude": 12.333,
        "Longitude": -22.123,
        "TruckName": "Sample Truck Name",
        "ESN": "Sample ESN",
        "Speed": 55.4,
        "Bearing": 47.38,
        "FixTime": "2018-03-12T19:22:02.2191606-04:00"
      }
    ]
  }
]
URL base/GPS/AVLListener/SubmitAVL
Action POST
Description Takes a single AVL Entry record using the specified format.
Parameters
Name Required? Code Description
DeviceID Yes Integer The ID of a truck in the M4 database.
Latitude Yes Double The latitude
Longitude Yes Double The longitude
TruckName No String The name of the truck
ESN No String The ESN.
Speed No Double The current MPH.
Bearing No Decimal The compass bearing in degrees
FixTime Yes DateTime The date/time the entry was logged at the vehicle/GPS device.
Sample JSON Package 
    {
            "DeviceID": "DeviceID as specified in Truck list",
            "Latitude": 12.333,
            "Longitude": -22.123,
            "TruckName": "Sample Truck Name",
            "ESN": "Sample ESN",
            "Speed": 55.4,
            "Bearing": 47.38,
            "FixTime": "2018-03-12T19:22:02.2191606-04:00"
    }
Returns A JSON System Message data object stating whether the submission was successful.
Sample Return Object 
        {
            "Message": "New AVL submitted successfully at 2/13/2018 11:12:06 AM."
        }
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

Any additional fields that are not a part of the specified JSON spec will be stored as additional package data in the database.

Latitude:
  • Latitude must be in the valid defined range for a latitudinal value.
Longitude:
  • Longitude must be in the valid defined range for a longitudinal value.
Speed:
  • Speed can either be null or, if specified, must be a value greater than or equal to zero.
Bearing:
  • Bearing can either be null or, if specified, must be within the range 0 to 360.
URL base/GPS/AVLListener/SubmitAVLGroup
Action POST
Description Takes a collection of AVL Entry records using the specified format.
Parameters
Name Required? Code Description
DeviceID Yes Integer The ID of a truck in the M4 database.
Latitude Yes Double The latitude
Longitude Yes Double The longitude
TruckName No String The name of the truck
ESN No String The ESN.
Speed No Double The current MPH.
Bearing No Decimal The compass bearing in degrees
FixTime Yes DateTime The date/time the entry was logged at the vehicle/GPS device.
Sample JSON Package 
 [
		  {
			"DeviceID": "DeviceID as specified in Truck list",
			"Latitude": 12.333,
			"Longitude": -22.123,
			"TruckName": "Sample Truck Name",
			"ESN": "Sample ESN",
			"Speed": 55.4,
			"Bearing": 47.38,
			"FixTime": "2018-03-12T19:22:02.2191606-04:00"
		  },
		  {
			"DeviceID": "DeviceID as specified in Truck list",
			"Latitude": 12.333,
			"Longitude": -22.123,
			"TruckName": "Sample Truck Name",
			"ESN": "Sample ESN",
			"Speed": 55.4,
			"Bearing": 47.38,
			"FixTime": "2018-03-12T19:22:02.2191606-04:00"
		  }
		]
Returns A JSON System Message data object stating whether the submission was successful.
Sample Return Object 
 
	{
		"Message": "New AVL List -- 2 item(s) submitted successfully at 2/13/2018 11:10:18 AM."
	}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

Any additional fields that are not a part of the specified JSON spec will be stored as additional package data in the database.

Latitude:
  • Latitude must be in the valid defined range for a latitudinal value.
Longitude:
  • Longitude must be in the valid defined range for a longitudinal value.
Speed:
  • Speed can either be null or, if specified, must be a value greater than or equal to zero.
Bearing:
  • Bearing can either be null or, if specified, must be within the range 0 to 360.

Was this article helpful?

Yes No

Related Articles