JSO API User Guide V1.2 SCI JSON API User Guide V2.0: Calamp Company Private

CALAMP COMPANY PRIVATE
JSO API User Guide V1.2
SCI JSON API User Guide V2.0
1
CONFIDENTIALITY NOTICE: This communication with its contents may contain confidential and/or legally privileged information. It is solely for
the use of the intended recipient(s). Unauthorized interception, review, use or disclosure is prohibited and may violate applicable laws including
the Electronic Communications Privacy Act. If you are not the intended recipient, please contact the sender and destroy all copies of the
communication.
Table of Contents
1. Objectives.............................................................................................................................................. 4
2. Overview ............................................................................................................................................... 4
3. Login and Authentication ...................................................................................................................... 7
3.1. Authentication .................................................................................................................................. 7
4. Enabling/Disabling of JSON Data Elements........................................................................................... 8
5. List of All Devices .................................................................................................................................. 8
5.1. Receiving a List of Devices ................................................................................................................ 8
6. Device Information ............................................................................................................................. 10
6.1. Sending and Receiving Device Information .................................................................................... 10
6.2. Available data elements.................................................................................................................. 11
7. Locations ............................................................................................................................................. 18
7.1. Receiving Location Information ...................................................................................................... 18
7.2. Location Description ....................................................................................................................... 19
7.3. Location Parameters ....................................................................................................................... 19
8. Shipments ........................................................................................................................................... 21
8.1. Receiving Shipment Information .................................................................................................... 21
8.2. Shipment Description...................................................................................................................... 22
8.3. Shipment Parameters ..................................................................................................................... 25
9. Message Streams and the Datapump API........................................................................................... 29
9.1. Requesting Messages Using the Datapump API ............................................................................. 29
9.2. Data elements ................................................................................................................................. 30
10. Alert Streams .................................................................................................................................. 35
10.1. Requesting Messages.................................................................................................................. 35
10.2. Data elements ............................................................................................................................. 36
11. Error Messages................................................................................................................................ 43
Appendix A – SCiOn™ Command API Data Elements ................................................................................. 46
2
communication.
Rev Date By Comments

1.0 02/16/2018 CMoore
1.2 3/20/2018 CMoore Corrections to authToken
1.3 5/3/2018 CMoore/DJudkins After full feature set introduced
1.4 8/8/2018 CMoore
2.0 3/4/19 DSulfridge Thermocouple tag support introduced
2.0 3/5/2019 DJudkins Added Overview and Error Messages Sections, minor
corrections and Appendix A
3
communication.
1. Objectives
This document provides user documentation for utilizing the SCiOn JSON API. Understanding the
following topics is essential for successful integration.
 Overview
 Login and Authentication
 Reading and writing device information
 Receiving device message streams
 Reading and writing shipment configuration information
 Receiving shipment event streams
 Error Messages
For each feature, demonstration of capabilities will be made using Postman, available at:
https://www.getpostman.com/
NOTES:
 The JSON interface supports all SC1000 family devices and tags.
 Postman functionality has been verified with Windows version and a Mac version.
https://app.getpostman.com/app/download/win64
https://app.getpostman.com/app/download/osx64
2. Overview
Programmatic integration with the SCiOn™ Command platform is accomplished via JSON (JavaScript
Object Notation). JSON is a lightweight data-interchange format. It is easy for humans to read and
write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript
Programming Language, Standard ECMA-262 3rd Edition - December 1999. JSON is a text format
that is completely language independent but uses conventions that are familiar to programmers of
the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others.
These properties make JSON an ideal data-interchange language.
The JSON API data is categorized by a use case category, Asset Management or Supply Chain. See
appendix A for specific data elements available for each use case. Essentially, the Supply Chain use
case involves shipments of product or materials. The Asset Management use case involves tracking
and monitoring assets.
Why does the use case make a difference when integrating with SCiOn™ Command via the JSON
API’s? The Supply Chain use case makes use of shipment tables to define how a SCI device or tag is
associated with a shipment. The Asset Management use case does not use shipments. Which API
data elements are utilized are determined by the use or non-use of shipments.
Note: The Supply Chain use case is also known as “paired mode” in the SCiOn™ Command platform.
Devices are paired with shipments. The Asset Management use case is also known as “unpaired
4
communication.
mode” in the SCiOn™ Command platform. Customers that do not use the Supply Chain use case in
SCiOn™ Command and retrieve the device data via the JSON API’s can and do emulate the Supply
Chain use case in their own platforms.
All SCiOn™ Command JSON API’s must include a valid value for the Calamp-Services-App key in the
API header.
Data elements for each API can be enabled in or disabled for each SCiOn™ Command account
depending on requirements.
The version 2.0 set of SCiOn™ Command JSON API’s consist of:
1. Authentication – an HTTP POST to obtain an authorization token (authToken) cookie that will
be utilized and is required as a header value for all subsequent SCiOn™ Command JSON API
calls. The authToken parameter is used as a header value for all subsequent API calls. If not
utilized, the authToken expires in one hours and must be re-instantiated to get a new
authToken.
2. deviceList – an HTTP Post to obtain a list of every device (that are not tags) in the account
specified by the value of the authToken associated with the account.
3. devicecommands – an HTTP POST to obtain (read) the current device settings and device
status of a specific device identified by a deviceId (Mobile Device Number) or a deviceId (tag
serial number). Also, the devicecommands API is used to change (write) specific device
settings. When writing device settings, the devicecommands API calls application functions to
send commands over the air (OTA) to devices when they next communicate with the SCiOn™
Command platform. Multiple devicecommands write API calls are queued to the SCiOn™
Command platform for processing in a first in/first out order. The following groups of data are
currently available via the devicecommands API is described in Table 2.1.
devicecommands API Subsections

devicecommands Type Description Devices API Index
Subsection Supported
deviceSettings read/write Provides device SC1004, deviceId =
identification, device SC1004V, MDN
properties and changing SC1102
of device control features
deviceLog Read Provides GPS location, SC1004, deviceId =
weather conditions and SC1004V, MDN
location accuracy SC1102 (no
information GPS)
deviceReport Read Provides device sensor SC1004, deviceId =

data, device state data, SC1004V, MDN
cellular state data, wifi
5
communication.
state data, device battery SC1102 (no

state and charging state GPS)
information
tempLog read Provides temperature SC1004, deviceId =
readings from the device SC1004V MDN
that have been logged.
Logged temperature
readings from the device
are readings that are
stored on the device. The
device will store
temperature sensor
readings when cellular or
wifi communications are
not available to the device
slaveList Read Provides the list of tags SC1004, deviceId =
that have recently been SC1004V MDN
detected by the device
tagTemp Read Provides tag temperature Logging and deviceId =
readings, logged and non- non-logging Tag Serial
logged sensor tags Number
tagLog Read Provides current readings All Tags deviceId =
from a tag and parent Tag Serial
device information Number
tagHum Read Provides current tag Logging sensor deviceId =
humidity readings, logged tags Tag Serial
and not logged Number
tagProbeTempLog Read Provides current probe Temperature deviceId =
tag humidity readings, Probe tags Tag Serial
logged and not logged Number
Table 2.1 – devicecommands API Subsection Description
devicecommands API notes:
 The devicecommands API only returns the last reported values of the device. No
historical data can be retrieved by date ranges.
 All of the above subsections of the devicecommands API may be called individually or all
together in the same call.
 The devicecommands API only retrieves data for one specific device index. The API call
does not retrieve data for multiple deviceIds.
 If a data element is used in an API call that does not apply to the specific device type, a
null value is returned for that data element value.
4. Locations – an HTTP POST (read only) to retrieve location detail information. Locations are
known locations defined in the SCiOn™ Command platform for a specific account.
6
communication.
5. shipmentSettings – an HTTP POST (read/write) to retrieve and change shipment details
6. loadTag – an HTTP POST (read/write) to retrieve tag details associated with a shipment and
add has the ability to SCI tags to a shipment
7. Datapump APIs – an HTTP GET that pulls various data from SCiOn™ Command message
queues. The messages may be device messages, event messages or alert messages. The
datapump API currently supports reporting interval device messages (same content as the
devicecommands API), alert messages (SCiOn™ Command platform generated such as
geofence entry and exit) or event messages (messages generated by device events such as
stopped, moving and device sensor events).
Notes about Datapump APIs:
 Currently, the Datapump API’s must be called to pull the messages off the queues. This
is not a true publish/subscribe API at this time.
 The only parameter passed to the Datapump APIs is the number of messages to retrieve
off the Datapump accessible message queues for your SCiOn™ Command account. Only
1 to 100 messages may be retrieved with each Datapump API call.
 The messages pulled from the Datapump accessible message queues are pulled first in,
first out.
 The default retention period for messages in the Datapump message queues is 24
hours. Datapump messages not pulled off within 24 hours of their timestamp are
discarded.
 Device messages for devices that are shared with other accounts will produce
Datapump queue messages in all accounts the device is shared with.
3. Login and Authentication

The login/authentication protocol utilizes a username/password, and dynamically assigned cookie.
3.1. Authentication
To request a cookie from the SCiOn system, perform the following:
 Using Postman, create a POST to:

o https://json.scioncommand.com/connect/services/login?useAuthToken=true&User
name=<name>&Password=<password>
7
communication.
 Where <name> and <password> are for the JSON user that Calamp has provided you.
 Create a “header” with the following:
o Key – Calamp-Services-App, value - d8b98aad-cc6e-4899-a86d-e2848eaf03b4
 Send the POST and verify that an authToken Cookie is received.
NOTES:
 A cookie is automatically renewed during use. The cookie expires after 1 hour of inactivity, and a
new cookie must be requested.
 The IP address of the POST will transition to a DNS name in subsequent releases.
4. Enabling/Disabling of JSON Data Elements

The following describes how to provide access to data elements:
 Access to data is configured by Calamp.

 Access to data elements are independently enabled for reading, writing, message streams,
and alert streams.
 Detailed descriptions of all data fields are provided in subsequent sections.
5. List of All Devices

A list of all devices allocated to a company can be requested as shown below.
5.1. Receiving a List of Devices

To send and receive data information, perform the following:
 Using Postman, create a POST to

https://json.scioncommand.com/connect/devicelist
 Copy the Cookie received in the authentication response, per section 3.1.
o Key – Calamp-Services-App, Value - d8b98aad-cc6e-4899-a86d-e2848eaf03b4
o Key – Cookie – “authToken=”, Paste the cookie copied above.
8
communication.
9
communication.
6. Device Information
Subject to CalAmp configuration, the JSON interface provides write access to configurable
parameters, and read access to a wide variety of device specific information.
 Access to information is limited to the company of the JSON user.

 All information reflects the last reported or configured values.
 If access to an element is blocked through CalAmp API configuration, a <null> is provided.
 Malformed requests receive a {} response.
6.1. Sending and Receiving Device Information

To send and receive data information, perform the following:

https://json.scioncommand.com/{version}/connect/devicecommands
 Versioning is supported as of release 2. You may leave the version identifier blank to use the
previous version of the API or prepend v2/ to the URI.
o Certain parameters are only available in version 2 of the API.
 Send the POST. Response is contained in the body.
o NOTE: “device” will return a number, not a string
o NOTE: A query for deviceId is also supported
o NOTE: A deviceId and tagId query can be either a string or a number
10
communication.
6.2. Available data elements

The following provides and html file formatted list of all parameters, with example reads and writes.
Notes:
 Device information is queried by deviceId, and allows access to all device specific information.
 Tag information is queried by tagId, and allows access to tagTemp and tagLog information
only.
 The command/query is a JSON object which may contain a combination of the following fields.
 Access to fields must be enabled by CalAmp Customer Support.
device:
"device" is the Device ID, presented as a numerical value between 1 and 2^64.
For a device, it corresponds to the Mobile Number field of the Device Detail screen.
deviceId:
"deviceId" is the Device ID presented as a string.
For a device, it corresponds to the Mobile Number field of the Device Detail screen.
tagId:
"tagId" is the Tag ID and is a string.
It corresponds to the Tag Id of the Tag Report screen
read:
"1" requests status from SCiOn
"0" sends a configuration to SCiOn
11
communication.
 deviceSettings: (all device settings are indexed by deviceId.)

o assetId:
 READ ONLY: The internal reference used by SCiOn to track the device
o deviceId:
 READ ONLY: The unique identifier for the asset (tag or device)
o stationaryRate:
 READ/WRITE: The reporting interval if device is stationary
 Units: seconds
 Allowable values: 60, 180, 300, 450, 900, 1800, 3600, 7200, 14400,
28800, 43200, 64800, 86400
o deviceModel:
 READ ONLY: The device type
o firmware:
 READ ONLY: The firmware release currently installed in the device
o tempLogRate:
 READ/WRITE: The temperature sampling rate for the device
 Units: seconds
 Allowable values: 60, 180, 300, 450, 900, 1800, 3600, 0 (disabled)
o movementRate:
 READ/WRITE: The reporting interval while device is moving
 Units: seconds
28800, 43200, 64800, 86400, 0 (disabled)
o ignitionRate:
 READ/WRITE: The reporting interval while device is connected to external
power
 Units: seconds
28800, 43200, 64800, 86400, 0 (disabled)
o enableOceanMode:
 READ/WRITE: Enables ocean mode for the device
 Allowable values: false - disable, true - enable
o enableFlightMode:
 READ/WRITE: Enables flight mode for the device
 Allowable values: false - disable, true - enable
o stationaryT1:
 READ/WRITE: Notification that device has been stationary for specified time
 Units: minutes
 Allowable values: 1 to 1440, 0 (disabled)
o stationaryT2:
 READ/WRITE: Notification that device has been stationary for specified time
 Units: minutes
12
communication.
 Allowable values: 1 to 1440, 0 (disabled)

o zMicroDetection:
 READ/WRITE: Turns on the tag detection capability for an SC1000 family device.
 Allowable values: true or false
 NOTE: If zMicroDetection is true, or if zMicroStatus is true, tag detection
is on.
o zMicroStatus:
 READ ONLY: Indicates that a device is on an active shipment with a tag.
o alias:
 READ ONLY: Returns the SCiOn device alias.
 deviceLog - READ ONLY: (all device log information is indexed by deviceId or device.)
o latitude:
 the last reported latitude of device
 UNITS: degrees
 Allowable values: -90 to +90
o longitude:
 the last reported longitude of device
 UNITS: degrees
 Allowable values: -180 to +180
o reportingRate:
 the stationaryRate as reported by the device
 Units: seconds
28800, 43200, 64800, 86400
o numberOfSatellites:
 number of GPS satellites
 Allowable values: 1 to 20
o streetAddress:
 reported street address
 Allowable values: textual string
o lastReport:
 Epoch datetime of last report
o speed:
 Speed reported in kph
o track:
 Direction of travel - textual
o skyConditions:
 Sky conditions - textual
o precipitation:
 rain information – textual
o usedSigma:
 Location accuracy in meters
13
communication.
o gpsSigma:
 GPS location accuracy in meters
o lastReport:
 Epoch datetime of last device report
 deviceReport - READ ONLY: (all device report information is indexed by deviceId or device.)
o temperature:
 temperature as reported - in degC
o batteryVoltage:
 device voltage as reported - in mV
o ignitionStatus:
 ignition status - 1 if on, 0 if off
o externalPowerStatus:
 external power status - 1 if on, 0 if off
o mcc:
 mobile country code of serving cell
o mnc:
 mobile network code of serving cell
o light:
 light value as reported
o shock:
 shock in mg
o tilt:
 tilt in degrees
o humidity:
 humidity in percent
o shockType:
 impact or drop
o ssid:
 SSID of first WiFi network reported
o charging:
 device is charging (true or false)
o wifi:
 all wifi networks observed in the last report
 wifi - READ ONLY:

o mac:
 the MAC address of the wifi router
o rssi:
 the relative signal strength of the wifi signal
o ssid:
 the SSID of the wifi router
14
communication.
 tempLog - READ ONLY: (all temp log information is indexed by deviceId or device.)
o Note: Only the last temperature reading will be provided.
o Bulk transfer of data is required for full temperature log extraction.
o temperature:
 a single temperature from device level temperature logging, reading in degC
o time:
 the epoch timestamp of the temperature reading
 slaveList - READ ONLY: (all slave list information is indexed by deviceId or device.)
o tagNumber:
 an array of tags seen by the device
 tagTemp - READ ONLY: (all tagTemp information is indexed by tagId.)

o Note: Only the last temperature reading is provided.
o temperature:
 a single temperature from the tag temperature log, reading in degC
o time:
o deviceId:
 (V2 OR LATER) corresponds to the ID of the Tag
o log:
 (V2 OR LATER) indicates if the data is a current reading or a logged reading
 tagProbeTempLog (V2 OR LATER) - READ ONLY: (all tagProbeTempLog information is indexed by

tagId.)
o temperature:
 a single temperature from the tag thermocouple log, reading in degC
o time:
 the epoch timestamp of the temperature reading from the thermocouple
o deviceId:
 corresponds to the ID of the Tag
o log:
 indicates if the data is a current reading or a logged reading
 tagHum - READ ONLY: (all tagHum information is indexed by tagId.)

o Note: Only the last humidity reading is provided.
o humidity:
 a single humidity from the tag humidity log
15
communication.
o time:
 the epoch timestamp of the humidity reading
o deviceId:
o log:
 tagLog - READ ONLY: (all tagLog information is indexed by tagId.)

o deviceId:
 corresponds to Asset Tag Number - unique identifier of device
o assetId:
 internal number used to reference the device
o reportingDeviceId:
 device reporting the tag data
 "null" if device does not belong to company requesting data
o latitude:
 latitude as reported by reporting device in degrees
o longitude:
 longitude as reported by reporting device in degrees
o batteryVoltage:
 Battery Voltage of the tag in mV
o temperature:
 Temperature as reported by tag in degC
o lastReport:
 Epoch timestamp of last report
o light:
 light value as reported by tag
o shock:
 shock in mg as reported by tag
o tilt:
 tilt in degrees as reported by tag
o humidity:
 humidity in percent as reported by tag
o rssi:
 signal strength of tag transmission
o masterDeviceId (V2 OR LATER):
 id of the device that is the master of the tag
Example write message:
Request:
{
"device": 72308628870135997,
16
communication.
"read": 0,
"deviceSettings": {
"stationaryRate": 600,
"enableFlightMode": true
}
}
Response:
{
"device": 72308628870135997,
"deviceSettings": {
"stationaryRate": 600,
"enableFlightMode": true
}
}
Example read message:
Request:
{
"deviceId": “72308628870135997”,
"read": 1,
"deviceSettings": {
"deviceId":null
"assetId":null
},
"deviceLog": {
"latitude":null,
"longitude":null,
"lastReport":null
},
"deviceReport": {
"batteryVoltage":null,
"temperature":null
}
}
Response:
{
"device": 72308628870135997,
"deviceSettings": {
"assetId": 15512
"deviceId":"72308628870135997",
},
"deviceLog": {
17
communication.
"latitude": 33.000166,
"longitude": -96.75227,
"lastReport": 1520867223197
},
"deviceReport": {
"batteryVoltage": 100,
"temperature": 24.56
}
}
Request:
{
"tagId": “72308628870194046”,
"read": 1,
"tagLog": {
"reportingDeviceId":null,
"temperature":null
}
}
Response:
{
"tagId": "72308628870194046",
"tagLog": [
{
"reportingDeviceId": "72308628870138927",
"temperature": 20
}
]
}
7. Locations
7.1. Receiving Location Information

To receive location information, perform the following:

https://json.scioncommand.com/{version}/connect/locations
18
communication.
7.2. Location Description

Locations can be read using the following API.
Notes:
 Only locations defined for the company of the JSON User can be examined.
 Data can only be read. Writes are not supported
An example read is shown below:
7.3. Location Parameters

A complete list of available parameters is presented below:
The command/query is a JSON object which may contain a combination of the following fields.
Access to fields must be enabled by Calamp Customer Support.

19
communication.
locationName:
"locationName" is the textual name of the location, as configured in SCiOn
read:
 locations:
o All elements are READ ONLY.
o locationName:
 The textual name of the location
o latitude:
 The latitude of the location
o longitude:
 The longitude of the location
o locationId:
 The internal SCiOn reference number for the location
o radius:
 The radius in meters of the location
o address1:
 The textual field as entered in SCiOn
o address2:
o city:
o state:
o zip:
o country:
o locationType:
Request:
{
"locationName": "Cairo",
"read": 1,
"locations":{
"locationName": null,
20
communication.
"locationId": null,
"latitude": null,
"longitude":null,
"radius":null,
"address1":null,
"address2":null,
"city":null,
"state":null,
"zip":null,
"country":null,
"locationType":null
}
}
Response:
{
"response": {
"locationId": 9482,
"latitude": 30.041952,
"longitude": 31.232711,
"radius": 3219,
"address1": "Amrika El Latiniah Street",
"address2": "",
"city": "",
"state": "Cairo",
"zip": "7667",
"country": "Egypt",
"locationType": "R"
},
"errors": null,
"Message": null
}
8. Shipments
8.1. Receiving Shipment Information

To receive shipment information, perform the following:

https://json.scioncommand.com/{version}/connect/shipmentdetails
21
communication.

 Versioning is supported as of release 2. You may leave the version identifier blank to use
the previous version of the API or prepend v2/ to the URI.
8.2. Shipment Description

Shipments can be created and modified using the shipment JSON interface. An example
shipment creation, read and modification are shown below:
1. Shipment creation requires the following:

 A “shipmentNo” that is not currently in use on an open shipment.
 A “shipmentId” of 0, indicating that this is a new shipment request instead of a
modification of an existing shipment.
 “read” of 0, indicating this is a write.
 7 mandatory “shipmentSettings” elements
o “deviceId” indicating what device is to be used
 Must be assigned to the company
 Must not be on an existing shipment
o “carrierId” or “carrierName”, as created for the company
o “deviceDeployment”, the epoch time that the device is deployed to the shipment
o “destinationId”, the ID of the destination for the shipment, as defined in Locations.
o “originId”, the ID of the shipment point of origination, as defined in Locations.
o “trailer”, a textual field indicating trailer information.
o “seal”, a textual field indicating seal information
 The response contains the “shipmentId”, as assigned by the system.
22
communication.
2. To modify a shipment, both “shipmentNo” and “shipmentId” are required.
23
communication.
3. Reads can be performed by either the “shipmentNo” or the “shipmentId”. The following is
required/provided:
 Query by “shipmentNo” will provide information on all shipments with that name.
 Query by “shipmentId” will provide information from the specified shipment only.
24
communication.
8.3. Shipment Parameters

The following parameters are available for shipments:
The command/query is a JSON object which may contain a combination of the following fields.
Access to fields must be enabled by Calamp Customer Support.
shipment:
shipmentNo:
READ/WRITE: The textual name of the shipment
shipmentId:
READ ONLY: The system assigned identifier of the shipment
Creating a shipment requires shipmentId to be "0"
read:
25
communication.

"0" creates a shipment if shipmentId=0, writes to a shipment if shipmentId is non-zero.
 shipmentSettings:
o shipmentNo:
 READ/WRITE: The textual name of the shipment
o shipmentId:
 READ ONLY: The system assigned identifier of the shipment
 Creating a shipment requires shipmentId to be "0"
o assetId:
 READ ONLY: The system assigned identifier for the device while on this load
o deviceId:
 READ/WRITE: The tracking device identifier
o carrierId:
 READ/WRITE: The carrier identifier, selected from one of the company carriers
o carrierCode:
 READ/WRITE: The textual representation of the carrier, uniquely mapped to a
carrierId
o trailer:
 READ/WRITE: The textual name of the trailer.
o seal:
 READ/WRITE: The textual name of the trailer.
o originId:
 READ/WRITE: locationId for the shipment origin
o destinationId:
 READ/WRITE: locationId for the shipment destination
o deviceDeployment:
 READ/WRITE: The epoch time that the device was deployed
o departureTime:
 READ/WRITE: The epoch time that the shipment left origin
o arrivalTime:
 READ/WRITE: The epoch time that the shipment arrived
o autofillTime:
 READ/WRITE: Checkbox selecting that times are to automatically populated
o fenceId:
 READ/WRITE: The textual field as entered in SCiOn
o status:
 READ/WRITE: The textual field indicating shipment status
o appointmentTime:
 READ/WRITE: The epoch time for appointments
o shipmentMode:
 READ/WRITE: The textual field as selected in SCiOn
o shipmentGuid:
26
communication.

o tractorId:
o tractorState:
o tractorLicense:
o tractorFeatures:
o driver1:
o driver1State:
o driver1License:
o driver1Phone:
o driver2:
o driver2State:
o driver2License:
o driver2Phone:
o trackerPlacement:
o trailerState:
o trailerFeatures:
o trailerLicense:
 loadTag:
o shipmentId:
 READ: The system assigned identifier of the shipment
o tagNumber:
 READ/WRITE: The TagId
o originChecked:
 READ/WRITE: Enables tag specific originId
o destinationChecked:
 READ/WRITE: Enables tag specific destinationId
27
communication.
o unitNumberChecked:
 READ/WRITE: Enables tag specific unit indicator
o tagUrlRecipientChecked:
 READ/WRITE: Enables tag specific notification URL
o originId:
 READ/WRITE: The locationId in the case of originChecked selected
o destinationId:
 READ/WRITE: The locationId in the case of destinationChecked selected
o tagUrlRecipient:
 READ/WRITE: URL for notification if tagUrlRecepientChecked is enabled
o tagReported:
 READ: Tag has been detected in the shipment
o tagDestinationReached:
 READ: Tag has reached destination
o destinationArrival:
 READ: Tag has disconnected at destination
Request:
{
"read": 1,
"locations":{
"locationName": null,
"locationId": null,
"latitude": null,
"longitude":null,
"radius":null,
"address1":null,
"address2":null,
"city":null,
"state":null,
"zip":null,
"country":null,
"locationType":null
}
}
Response:
{
"response": {
"locationId": 9482,
28
communication.
"latitude": 30.041952,
"longitude": 31.232711,
"radius": 3219,
"address1": "Amrika El Latiniah Street",
"address2": "",
"city": "",
"state": "Cairo",
"zip": "7667",
"country": "Egypt",
"locationType": "R"
},
"errors": null,
"Message": null
}
9. Message Streams and the Datapump API

Subject to Calamp configuration, the JSON interface provides access to specified information from
all incoming messages.

 Each incoming report generates a message.
 The messages are placed in a queue and presented in groups of up to 100 messages at a time
 The content is configured on a per company basis, and is identical for all messages within a
company
 The data queue discards messages not retrieved within 24 hours of the report being received.
9.1. Requesting Messages Using the Datapump API

To request messages, perform the following:
 Using Postman, create a GET to

 https://json.scioncommand.com/{version}/connect/datapump/services/devices?numMess
ages=2
 Send the GET. Response is contained in the body.
 Versioning is supported as of release 2. You may leave the version identifier blank to use
the previous version of the API or prepend v2/ to the URI.
29
communication.
9.2. Data elements

The following provides an html file formatted list of all parameters, with example reads and
writes.
The notification is a JSON object which may contain a combination of the following fields.
Access to fields must be enabled by Calamp Customer Support
response:
numAppMessages:
The number of messages being sent (0 to 100)
results:
SC1000Messages: (N occurances of the SC1Message JSON content as defined below)
 deviceSettings:
o assetId:
 The internal reference used by SCiOn to track the device
o deviceId:
 The unique identifier for the asset (tag or device)
o stationaryRate:
 The reporting interval if device is stationary
 Units: seconds
o deviceModel:
 The device type
o firmware:
 The firmware release currently installed in the device
o tempLogRate:
 The temperature sampling rate for the device
30
communication.
 Units: seconds
o movementRate:
 The reporting interval while device is moving
 Units: seconds
o enableOceanMode:
 Enables ocean mode for the device
o enableFlightMode:
 Enables flight mode for the device
o stationaryT1:
 Notification that device has been stationary for specified time
 Units: minutes
o stationaryT2:
 Alert that device has been stationary for specified time
 Units: minutes
o zMicroDetection:
 Turns on the tag detection capability for an SC1000 family device.
is on.
o zMicroStatus:
 Indicates that a device is on an active shipment with a tag.
o ignitionRate:
 The reporting interval while device is connected to external power
 Units: seconds
o alias:
 Returns the SCiOn device alias.
 deviceLog - :
o latitude:
 UNITS: degrees
o longitude:
 UNITS: degrees
o reportingRate:
 Units: seconds
o streetAddress:
o lastReport:
o speed:
o track:
31
communication.

o skyConditions:
o precipitation:
 rain information - textual
o usedSigma:
o gpsSigma:
 deviceReport :
o temperature:
o batteryVoltage:
 device voltage as reported - in %
o ignitionStatus:
o mcc:
o mnc:
o light:
o shock:
 shock in mg
o tilt:
 tilt in degrees
o humidity:
o shockType:
 impact or drop
o ssid:
o charging:
o wifi:
 wifi:
o mac:
o rssi:
o ssid:
32
communication.
 tempLog :
o temperature:
o time:
 the Epoch timestamp of the temperature reading
 slaveList :
o tagNumber:
 the reported slave list
 tagTemp: (all tagTemp information is indexed by tagId.)

o temperature:
o time:
 the Epoch timestamp of the temperature reading
o deviceId:
o log:
 tagProbeTempLog (V2 OR LATER): (all tagProbeTempLog information is indexed by tagId.)

o temperature:
o time:
o deviceId:
o log:
 tagHum: (all tagHum information is indexed by tagId.)

o humidity:
o time:
o deviceId:
33
communication.

o log:
 tagLog : (all tagLog information is indexed by tagId.)

o deviceId:
o assetId:
o latitude:
o longitude:
o batteryVoltage:
 Battery Voltage of the tag in %
o temperature:
o lastReport:
o light:
o shock:
o tilt:
o humidity:
o rssi:
Example message:
{
"numAppMessages": 2,
"SC1000Message": {
"device": {
"deviceId"", 7212421234
}
"deviceLog": {
"latitude": 43.225:,
34
communication.
"longitude": 46,231,
"lastReport":15342356
},
"deviceReport": {
"batteryVoltage": 90,
"temperature": 86
},
"tagTemp": {
"time":15235234,
"temperature":82
}
}
"SC1000Message": {
"deviceLog": {
"latitude":,
"longitude":,
"lastReport":,
},
"deviceReport": {
"batteryVoltage":,
"temperature":,
},
"tagTemp": {
"time":,
"temperature":,
}
}
}
10. Alert Streams

Subject to Calamp configuration, the JSON interface provides access to specified information from
all incoming messages.

 Each event generates a message.
 The messages are placed in a queue and presented in groups of up to 100 messages at a time
 The content is configured on a per company basis, and is identical for all messages within a
company
 The data queue discards messages not retrieved within 24 hours of the report being
received.
10.1. Requesting Messages

To request messages, perform the following:
 Using Postman, create a GET to
35
communication.
http://json.scioncommand.com/{version}/connect/datapump/services/alerts/?numMessages
=100
o Key – Cookie – Paste the cookie copied above.
 Send the GET. Response is contained in the body.
10.2. Data elements

The following provides an html file formatted list of all parameters, with example reads and writes.
The notification is a JSON object which may contain a combination of the following fields:
response:
numAppMessages:
36
communication.
The number of messages being sent (0 to 100)
results:
SC1xxxMessages:
N occurrences of the SC1Message JSON content as defined below
 eventDetails:
o eventName:
 The name of the event, as assigned in SCiOn
o triggerUnitActivity:
 The name of the event trigger, as assigned in SCiOn
o Priority:
 The priority level of the event, as assigned in SCiOn
 deviceSettings:
o assetId:
 The internal reference used by SCiOn to track the device
o deviceId:
 The unique identifier for the asset (tag or device)
o stationaryRate:
 The reporting interval if device is stationary
 Units: seconds
o deviceModel:
 The device type
o firmware:
 The firmware release currently installed in the device
o tempLogRate:
 The temperature sampling rate for the device
 Units: seconds
o movementRate:
 The reporting interval while device is moving
 Units: seconds
o enableOceanMode:
 Enables ocean mode for the device
o enableFlightMode:
 Enables flight mode for the device
o stationaryT1:
 Notification that device has been stationary for specified time
 Units: minutes
o stationaryT2:
 Alert that device has been stationary for specified time
 Units: minutes
o zMicroDetection:
 Turns on the tag detection capability for an SC1000 family device.
37
communication.

is on.
o zMicroStatus:
 Indicates that a device is on an active shipment with a tag.
o ignitionRate:
 The reporting interval while device is connected to external power
 Units: seconds
o alias:
 Returns the SCiOn device alias.
 deviceLog:
o latitude:
 UNITS: degrees
o longitude:
 UNITS: degrees
o reportingRate:
 Units: seconds
o streetAddress:
o lastReport:
o speed:
o track:
o skyConditions:
o precipitation:
 rain information - textual
o usedSigma:
o gpsSigma:
 deviceReport :
o temperature:
o batteryVoltage:
 device voltage as reported - in %
o ignitionStatus:
38
communication.

o mcc:
o mnc:
o light:
o shock:
 shock in mg
o tilt:
 tilt in degrees
o humidity:
o shockType:
 impact or drop
o ssid:
o charging:
o wifi:
 wifi:
o mac:
o rssi:
o ssid:
 tempLog :
o temperature:
o time:
 slaveList :
o tagNumber:
 the reported slave list
 tagTemp: (all tagTemp information is indexed by tagId.)

39
communication.
o temperature:
o time:
o deviceId:
o log:
 tagProbeTempLog (V2 OR LATER): (all tagProbeTempLog information is indexed by tagId.)

o temperature:
o time:
o deviceId:
o log:
 tagHum: (all tagHum information is indexed by tagId.)

o humidity:
o time:
o deviceId:
o log:
 tagLog : (all tagLog information is indexed by tagId.)
o deviceId:
o assetId:
o latitude:
40
communication.
o longitude:
o batteryVoltage:
 Battery Voltage of the tag in %
o temperature:
o lastReport:
o light:
o shock:
o tilt:
o humidity:
o rssi:
 shipmentSettings:
o shipmentNo:
 The textual name of the shipment
o shipmentId:
 The system assigned identifier of the shipment
o assetId:
 The system assigned identifier for the device while on this load
o deviceId:
 The tracking device identifier
o carrierId:
 The carrier identifier, selected from one of the company carriers
o carrierCode:
 The textual representation of the carrier, uniquely mapped to a carrierId
o trailer:
 The textual name of the trailer.
o seal:
 The textual name of the trailer.
o originId:
 locationId for the shipment origin
o destinationId:
 locationId for the shipment destination
o deviceDeployment:
 The epoch time that the device was deployed
o departureTime:
41
communication.
 The epoch time that the shipment left origin

o arrivalTime:
 The epoch time that the shipment arrived
o autofillTime:
 Checkbox selecting that times are to automatically populated
o fenceId:
o status:
 The textual field indicating shipment status
o appointmentTime:
 The epoch time for appointments
o shipmentMode:
 The textual field as selected in SCiOn
o shipmentGuid:
o tractorId:
o tractorState:
o tractorLicense:
o tractorFeatures:
o driver1:
o driver1State:
o driver1License:
o driver1Phone:
o driver2:
o driver2State:
o driver2License:
o driver2Phone:
o trackerPlacement:
o driverSignature:
42
communication.
 loadTag:
o tagNumber:
 The TagId
o originChecked:
 Enables tag specific originId
o destinationChecked:
 Enables tag specific destinationId
o unitNumberChecked:
 Enables tag specific unit indicator
o tagUrlRecipientChecked:
 Enables tag specific notification URL
o originId:
 The locationId in the case of originChecked selected
o destinationId:
 The locationId in the case of destinationChecked selected
o tagUrlRecipient:
 URL for notification if tagUrlRecepientChecked is enabled
o tagReported:
 Tag has been detected in the shipment
o tagDestinationReached:
 Tag has reached destination
o destinationArrival:
 Tag has disconnected at destination
11. Error Messages

This section illustrates common error messages and the return values that are generated.
1. Invalid or expired authToken
<fieldset>
<h2>403 - Forbidden: Access is denied.</h2>
<h3>You do not have permission to view this directory
or page using the credentials that you supplied.</h3>
</fieldset>
2. Access a device that is not in the account associated with the supplied authToken account
{
"response": {},
"result": null,
"errors": "UnAuthorized Request!! You don't have permission for this device.",
"Message": null
}
43
communication.
3. Invalid Calamp-Services-App key.
<fieldset>
</fieldset>
4. Non-existent Calamp-Services-App key
<fieldset>
</fieldset>
5. Non-existent authToken on API call
<fieldset>
</fieldset>
6. Mal-formatted HTTP POST body
{}
7. Datapump API without numMessages parameter
{
"Message": "No HTTP resource was found that matches the request URI
'https://json.scioncommand.com/connect/datapump/services/devices'.",
"MessageDetail": "No action was found on the controller 'Connect' that matches the
request."
}
8. Datapump API with null numMessages parameter
{
"Message": "The request is invalid.",
"MessageDetail": "The parameters dictionary contains a null entry for parameter
'numMessages' of non-nullable type 'System.Int32' for method
'System.Net.Http.HttpResponseMessage GetDataPump(Int32, System.String)' in
44
communication.
'ReportingService.Controllers.ConnectController'. An optional parameter must be a

reference type, a nullable type, or be declared as an optional parameter."
}
45
communication.
Appendix A – SCiOn™ Command API Data Elements
The table below defines all data elements
SCiOn™ Command JSON API Data Elements

Shipment Data Elements Supply Asset Description Datatype Scale &
Chain Management Precision
shipmentNo Y Shipment String
Identification
Number
assetId Y Tracking Device ID String
Number (internal)
deviceId Y Tracking Device String
Serial Number
shipmentId y Shipment String
Identification
Number
carrierId Y Motor Carrier String
Name
carrierCode y Motor Carrier SCAC String
Code
trailer y Trailer Number String
seal y Seal Number String
originId y Geo Location – String
Origin
destinationId y Geo Location – String
Destination
deviceDeployment Y Shipment Creation DateTime
Time
departureTime y Origin Departure
Time
arrivalTime y Destination Arrival
Time
autofillTime y Automatic
Destination Arrival
Time
fenceId y Route/s ID
status y Shipment Status
appointmentTime y Appointment Time
shipmentMode y Mode of
Transportation
shipmentGuid y Shipment Specific
view only URL
tractorId y Tractor ID
46
communication.
tractorState y Tractor license

plate state
tractorLicense y Tractor license
plate number
tractorFeatures y Tractor Features
driver1 y Driver Name
driver1State y Driver license State
driver1License y Driver License
Number
driver1Phone y Driver Phone
Number
driver2State y Driver Name
driver2License y Driver License
Number
driver2Phone y Driver Phone
Number
trackerPlacement y Description of
tracking device
location
driver2 y Driver Name
trailerState y Trailer License Plate
State
trailerFeatures y Trailer Features
trailerLicense y Trailer License Plate
Number
Shipment Load Tag Supply Asset Description Datatype Scale &

shipmentId y Shipment ID
tagNumber y Tag ID on shipment
originChecked y
destinationChecked y
unitNumberChecked y
tagUrlRecipientChecked y
originId y Origin location ID
destinationId y Destination
location ID
tagUrlRecipient Y
tagReported Y
tagDestinationReached Y
destinationArrival y
Locations Supply Asset Description Datatype Scale &

locationName Y Y Geo Location Name
47
communication.
latitude Y Y Geo Location

Latitude
longitude Y Y Geo Location
Longitude
locationId Y Y Geo Location ID
Number
radius Y Y Geo Location
diameter in miles
address1 Y Y Geo Location
Address Field
address2 Y Y Geo Location
Address Field
city Y Y Geo Location City
state Y Y Geo Location State
zip Y Y Geo Location Zip
code
country Y Y Geo Location
Country Code
locationType Y Y Geo Location Type
Device Report Supply Asset Description Datatype Scale &

temperature Y Y Device
Temperature Value
C
batteryVoltage Y Y Device Battery
Voltage
ignitionStatus Y Y Device Ignition
Status
externalPowerStatus Y Y External Device
Power Attached
mcc Y Y Mobile Country
Code
mnc Y Y Mobile Network
Code
light Y Y Device Light
Measurement
shock Y Y Device Shock
Measurement
tilt Y Y Device Tilt
Measurement
humidity Y Y Device Humidity
Measurement
shockType Y Y Device Shock type
(Shock/ Drop)
48
communication.
ssid Y Y Strongest WiFi

network seen by
the device
charging Y Y Device Charging
status
Device Log Supply Asset Description Datatype Scale &

latitude Y Y Device Latitude
longitude Y Y Device Longitude
reportingRate Y Y Device Reporting
Rate
numberOfSatellites Y Y GPS Satellites
acquired
streetAddress Y Y Device Street
Address
speed Y Y Device Speed (GPS
Only)
track Y Y Device Heading
skyConditions Y Y Current
Atmospheric
Conditions
precipitation Y Y Current
Precipitation
Conditions
usedSigma Y Y Cell Location Error
gpsSigma Y Y GPS Location Error
lastReport Y Y Epoch date of
report
Slave List Supply Asset Description Datatype Scale &

tagNumber Y Y BLE Tags Seen String
Device Settings Supply Asset Description Datatype Scale &

assetId Y Y Tracking Device ID
Number (internal)
deviceId Y Y Tracking Device
Serial Number
stationaryRate Y Y Stationary
Reporting Rate
deviceModel Y Y Device Model
firmware Y Y Device Firmware
Version
49
communication.
tempLogRate Y Y Temperature
Logging Rate
movementRate Y Y Device Moving
Reporting Rate
enableOceanMode Y Ocean Mode
Enabled
enableFlightMode Y Flight Mode
Enabled
stationaryT1 Y Y Stationary
Notification Timer
stationaryT2 Y Y Stationary Alert
Timer
zMicroDetection Y Y Tag detection
enable
zMicroStatus Y Y Tag detection
status
ignitionRate Y
Alias Y Y Friendly name
assigned to device
Temp Log Supply Asset Description Datatype Scale &

temperature Y Logged BLE Tag
Temperature
time Y Logged BLE Tag
Time Stamp
Tag Log Supply Asset Description Datatype Scale &

deviceId Y Y BLE Tag ID
assetId Y Y BLE Tag ID
(internal)
reportingDeviceId Y Y Parent Unit ID that
is reporting the BLE
Tag
latitude Y Y BLE Tag Longitude
longitude Y Y BLE Tag Latitude
batteryVoltage Y Y BLE Battery Voltage
temperature Y Y BLE Temperature
Measurement
lastReport Y Y BLE Last Report
light Y Y BLE Light
Measurement
shock Y Y BLE Shock
Measurement
50
communication.
tilt Y Y BLE Tilt

Measurement
humidity Y Y BLE Humidity
Measurement
Rssi Y Y Radio signal
strength
masterDeviceId Y
Tag Temp Supply Asset Description Datatype Scale &

temperature Y Y BLE Tag
Temperature
time Y Y BLE Tag Time Stamp
deviceId (v2)
log (v2)
Tag Hum Supply Asset Description Datatype Scale &

humidity Y Y BLE Tag Humidity
deviceId Y Y BLE Tag Device Id
log Y Y (v2) logged
Tag Probe Temp Log Supply Asset Description Datatype Scale &
temperature Y Y BLE Tag External
Probe Temperature
(v2)
(v2)
deviceId Y Y BLE Tag Device Id
log Y Y (v2) logged
Event Details Supply Asset Description Datatype Scale &

Element
eventName Y Y Event Name
triggerUnitActivity Y Y Event Trigger
priority Y Y Event Priority
Alert Id Supply Asset Description Datatype Scale &

Element
alertId Y Y Unique alert Id
(internal)
51
communication.
alertDefinition Y Y Name of the event

that triggered
dateCreated Y Y Date alert occurred
Urgency Y Y Priority of alert
WIFI Supply Asset Description Datatype Scale &

Element
mac Y Y MAC address of wifi
router
rssi Y Y Signal strength of
Wifi network
ssid Y Y Name/ID of wifi
network
52
communication.

JSO API User Guide V1.2 SCI JSON API User Guide V2.0: Calamp Company Private

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

JSO API User Guide V1.2 SCI JSON API User Guide V2.0: Calamp Company Private

Hochgeladen von

Copyright:

Verfügbare Formate

CALAMP COMPANY PRIVATE

JSO API User Guide V1.2

SCI JSON API User Guide V2.0

Rev Date By Comments

devicecommands API Subsections

deviceReport Read Provides device sensor SC1004, deviceId =

state data, device battery SC1102 (no

devicecommands API notes:

5. shipmentSettings – an HTTP POST (read/write) to retrieve and change shipment details

Notes about Datapump APIs:

3. Login and Authentication

 Using Postman, create a POST to:

4. Enabling/Disabling of JSON Data Elements

 Access to data is configured by Calamp.

5. List of All Devices

5.1. Receiving a List of Devices

 Using Postman, create a POST to

 Access to information is limited to the company of the JSON user.

6.1. Sending and Receiving Device Information

 Using Postman, create a POST to

6.2. Available data elements

 deviceSettings: (all device settings are indexed by deviceId.)

 Allowable values: 1 to 1440, 0 (disabled)

 wifi - READ ONLY:

 tagTemp - READ ONLY: (all tagTemp information is indexed by tagId.)

 tagProbeTempLog (V2 OR LATER) - READ ONLY: (all tagProbeTempLog information is indexed by

 tagHum - READ ONLY: (all tagHum information is indexed by tagId.)

 tagLog - READ ONLY: (all tagLog information is indexed by tagId.)

Example write message:

Example read message:

7.1. Receiving Location Information

 Using Postman, create a POST to

7.2. Location Description

An example read is shown below:

7.3. Location Parameters

Access to fields must be enabled by Calamp Customer Support.

Example read message:

8.1. Receiving Shipment Information

 Using Postman, create a POST to

o Key – Cookie – “authToken=”, Paste the cookie copied above.

8.2. Shipment Description

1. Shipment creation requires the following:

2. To modify a shipment, both “shipmentNo” and “shipmentId” are required.

8.3. Shipment Parameters

Access to fields must be enabled by Calamp Customer Support.

"1" requests status from SCiOn

 READ/WRITE: The textual field as entered in SCiOn

Example read message:

9. Message Streams and the Datapump API

 Access to information is limited to the company of the JSON user.

9.1. Requesting Messages Using the Datapump API

 Using Postman, create a GET to

9.2. Data elements

Access to fields must be enabled by Calamp Customer Support

 Direction of travel - textual

 the SSID of the wifi router

 tagTemp: (all tagTemp information is indexed by tagId.)

 tagProbeTempLog (V2 OR LATER): (all tagProbeTempLog information is indexed by tagId.)

 tagHum: (all tagHum information is indexed by tagId.)

 (V2 OR LATER) corresponds to the ID of the Tag

 tagLog : (all tagLog information is indexed by tagId.)

10. Alert Streams

 Access to information is limited to the company of the JSON user.