1. Retrieve your API Key
- Visit https://app.charterup.com/
- Log in
- Click your username in the top right
- Your API key will appear in the account settings panel. Note: Contact your account representative to have an API key assigned
Reminder: The API key is rather lengthy. Make sure to copy the entire key!
Reminder: If your API key is missing, contact support for API access to be activated on your account.
Reminder: Now is a good time to read about API rate limits.
2. API Request - Validate API Key
- Returns a message indicating the validity of the API key.
- This API request is entirely optional. It is a simple request that can be helpful in building your initial API request code.
Sample request
HTTPS Post to https://api.charterup.com/api/v2/ with the following JSON Payload:
{
"commandstring": "validate_api_key",
"token": "Insert_My_API_Key"
}
JSON Details
commandstring |
String |
API Request Command |
token |
String |
Your API Key |
Sample response
{
"CommandString": "validate_api_key",
"timestamp": "12/06/2017 11:14:41",
"message": "Valid API key."
}
JSON Details
commandstring |
String |
Requested API Command |
timestamp |
String |
DateTime (UTC) of server response. Format: MM/dd/yyyy HH:mm:ss |
message |
String |
API key validation details |
3. API Request - Get Devices
Returns a list of devices currently assigned to your organization's reservations.
Sample request
HTTPS Post to https://api.charterup.com/api/v2/ with the following JSON Payload:
{
"commandstring": "get_devices",
"token": "Insert_My_API_Key"
}
JSON Details
commandstring |
String |
API Request Command |
token |
String |
Your API Key |
Sample Response
{
"CommandString": "get_devices",
"timestamp": "12/06/2017 11:14:41",
"rate_limit_stats": "10sec_rate:1/20 1min_rate:9/60 1hour_rate:12/130",
"data":[{
"deviceId": 7971,
"OrgID": 7,
"imsi": 0,
"iccid": "",
"imei": "555108001841555",
"serviceProvider": "ATT",
"lastIP": "0.0.0.0",
"lastReportTime": "04/25/2016 04:05:50",
"lastReportGPSIsCellTower": false,
"lastReportLatitude": "25.2094621",
"lastReportLongitude": "-105.6478600",
"lastReportUpdateTime": "04/25/2019 04:05:50",
"lastReportVoltage": "3980.0000",
"customerLabel": "555108001841555",
"consumerLabel": "555108001841555",
"consumerKey": "55-555",
"customerDesc": "",
"consumerDesc": "",
"firmwareVersion": "5.5.5",
"serviceHours": 0,
"serviceHours_Date": "02/16/2006 05:32:17",
"serviceMileage": -1,
"serviceMileage_Date": "02/16/2006 05:32:17",
"serviceHours_Start": -1,
"serviceMileage_Start": -1,
"serviceMileage_Mode": 0,
"Image_URL": "https://vtx-images.s3.amazonaws.com/vqam/custom/device-images/22901-0d6a87b5-c16e-4c47-adf1-0a290289ea73.jpg",
"ProductID": 37,
"DeviceTypeID": 2
}]
}
JSON Details
commandstring |
String |
Requested API Command |
timestamp |
String |
DateTime (UTC) of server response. Format: MM/dd/yyyy HH:mm:ss |
data[] |
Array |
List of devices |
Reminder: Within the "device" object, note the IMEI field. This will be helpful in retrieving device reports via the get_reports_single_device API command.
4. API Request - Get Device
Returns information for a single device.
Sample request
HTTPS Post to https://api.charterup.com/api/v2/ with the following JSON Payload:
{
"commandstring": "get_device",
"token": "Insert_My_API_Key"
"identifier": "013108001841853",
}
JSON Details
commandstring |
String |
API Request Command |
token |
String |
Your API Key |
identifier |
String |
Device's IMEI or DeviceID |
Sample Response
{
"CommandString": "get_device",
"timestamp": "12/06/2017 11:14:41",
"rate_limit_stats": "10sec_rate:1/20 1min_rate:9/60 1hour_rate:12/130",
"data":[{
"deviceId": 7971,
"OrgID": 7,
"imsi": 0,
"iccid": "",
"imei": "013108001841853",
"serviceProvider": "ATT",
"lastIP": "0.0.0.0",
"lastReportTime": "04/25/2019 04:05:50",
"lastReportGPSIsCellTower": false,
"lastReportLatitude": "25.2094621",
"lastReportLongitude": "-105.6478600",
"lastReportReceivedTime": "04/25/2019 04:05:50",
"lastReportVoltage": "3980.0000",
"customerLabel": "555108001841555",
"consumerLabel": "555108001841555",
"consumerKey": "55-555",
"customerDesc": "",
"consumerDesc": "",
"firmwareVersion": "5.5.5",
"serviceHours": 0,
"serviceHours_Date": "02/16/2006 05:32:17",
"serviceMileage": -1,
"serviceMileage_Date": "02/16/2006 05:32:17",
"serviceHours_Start": -1,
"serviceMileage_Start": -1,
"serviceMileage_Mode": 0,
"Image_URL": "https://vtx-images.s3.amazonaws.com/vqam/custom/device-images/22901-0d6a87b5-c16e-4c47-adf1-0a290289ea73.jpg",
"ProductID": 37,
"DeviceTypeID": 2
}]
}
JSON Details
commandstring |
String |
Requested API Command |
timestamp |
String |
DateTime (UTC) of server response. Format: MM/dd/yyyy HH:mm:ss |
identifier |
String |
Device's IMEI or DeviceID |
data[] |
Array (Length = 1) |
device details |
Reminder: Within the "device" object, note the IMEI field. This will be helpful in retrieving device reports via the get_reports_single_device API command.
5. API Request - Get Reports - Single Device
- Returns an array of reports and associated details for the specified device.
- It is strongly recommended to utilize the datetime_start and datetime_end filter options. Some devices produce many reports.
- Report Limit: 3000 if date-range-filters represents a timespan of less than 2.1 days
- Report Limit: 500 if date-range-filters represents a timespan of greater than 2.1 days or if the date-range-filters are not supplied
- It is also recommended to utilize the "coredataonly": "true" option. This will be sufficient in 95% of deployments. You may set this to false to retrieve verbose records.
Sample request
HTTPS Post to https://api.charterup.com/api/v2/ with the following JSON Payload:
{
"commandstring": "get_reports_single_device",
"identifier": "013108001841853",
"datetime_start": "02/20/2016 00:00:00",
"datetime_end": "02/22/2016 00:00:00",
"coredataonly": true,
"token": "Insert_My_API_Key"
}
JSON Details
commandstring |
String |
Requested API Command |
identifier |
String |
Device's IMEI or DeviceID |
datetime_start |
String |
Retrieve reports after this datetime (UTC). Format: MM/dd/yyyy HH:mm:ss |
datetime_end |
String |
Retrieve reports before this datetime (UTC). Format: MM/dd/yyyy HH:mm:ss |
coredataonly |
Boolean |
(optional) If true, the API only returns core report data along with GPS coordinates. This is excellent for minimizing API request & client-side processing time. This is the option to use in 95% of deployments. |
token |
String |
Your API Key |
Sample Response
{
"CommandString": "get_reports_single_device",
"timestamp": "12/06/2017 11:14:41",
"rate_limit_stats": "10sec_rate:1/20 1min_rate:9/60 1hour_rate:12/130",
"data": [{
"reportId": 880417,
"deviceId": 5555,
"iccid": "",
"imei": "555108001841555",
"receivedDate": "02/20/2016 00:01:30",
"updateTime": "02/20/2016 00:01:01",
"longitude": -95.3206359,
"latitude": 36.2515538,
"voltage1": 4051,
"temp1": 297,
"GPS_isCellTower": false,
"GPS_speed": 4,
"GPS_heading": 341
}]
}
Core Report JSON Details
reportId |
Int32 |
Report identifier |
deviceId |
Int32 |
Device identifier |
iccid |
String |
Integrated circuit card identifier |
imei |
String |
International Mobile Station Equipment Identity |
receivedDate |
String |
UTC Datetime that the server received the device report. Format: MM/dd/yyyy HH:mm:ss |
updateTime |
String |
UTC Datetime that the device submitted the report. Format: MM/dd/yyyy HH:mm:ss |
longitude |
Float |
GPS Longitude |
latitude |
Float |
GPS Latitude |
voltage1 |
decimal |
Last report voltage in millivolts. |
temp1 |
Int32 |
Temperature measurement 1. For DeviceTypeID between 1 and 5 this is in Kelvin. For DeviceTypeID 14 or 15 this is in celsius. |
GPS_isCellTower |
Boolean |
If "false", then the latitude and longitude were calculated by GPS satellite signals. If "true" then cell-trilateration was used (much less accurate). |
GPS_speed |
Int32 |
Speed as calculated by GPS in MPH |
GPS_heading |
Int32 |
Heading as calculated by GPS |
5.1. API Request - Retrieve Reports - All Devices
- Returns an array of reports and associated details for your organization.
- Many organizations benefit by not using this command in favor of get_reports_single_device
- Parameter datetime_start is required.
- Parameter datetime_end is optional and may be, at most, 24 hours beyond datetime_start.
- It is also recommended to utilize the "coredataonly": "true" option. This will be sufficient in 95% of deployments. You may set this to false to retrieve verbose records.
- At most 500 reports are returned. If you keep bumping into this limit, please tighten up the time range parameters.
- If you need increased rate limits, please contact support with a detailed use case.
Sample request
HTTPS Post to https://api.charterup.com/api/v2/ with the following JSON Payload:
{
"commandstring": "get_reports_all_devices",
"datetime_start": "02/20/2016 00:00:00",
"datetime_end": "02/20/2016 03:59:59",
"coredataonly": "true",
"token": "Insert_My_API_Key"
}
JSON Details
commandstring |
String |
Requested API Command |
datetime_start |
String |
Required: Retrieve reports after this datetime (UTC). Format: MM/dd/yyyy HH:mm:ss |
datetime_end |
String |
Optional, but strongly recommended: Retrieve reports before this datetime (UTC). Format: MM/dd/yyyy HH:mm:ss |
coredataonly |
Boolean |
(optional) If true, the API only returns core report data along with GPS coordinates. This is excellent for minimizing API request & client-side processing time. This is the option to use in 95% of deployments. |
token |
String |
Your API Key |
Sample Response
{
"CommandString": "get_reports_all_devices",
"timestamp": "12/06/2017 11:14:41",
"rate_limit_stats": "10sec_rate:1/20 1min_rate:9/60 1hour_rate:12/130",
"data": [{
"reportId": 880417,
"deviceId": 5555,
"iccid": "",
"imei": "555108001841555",
"receivedDate": "02/20/2016 00:01:30",
"updateTime": "02/20/2016 00:01:01",
"longitude": -95.3206359,
"latitude": 36.2515538,
"voltage1": 4051,
"temp1": 297,
"GPS_isCellTower": false,
"GPS_speed": 4,
"GPS_heading": 341
}]
}
Core Report JSON Details
reportId |
Int32 |
Report identifier |
deviceId |
Int32 |
Device identifier |
iccid |
String |
Integrated circuit card identifier |
imei |
String |
International Mobile Station Equipment Identity |
receivedDate |
String |
UTC Datetime that the server received the device report. Format: MM/dd/yyyy HH:mm:ss |
updateTime |
String |
UTC Datetime that the device submitted the report. Format: MM/dd/yyyy HH:mm:ss |
longitude |
Float |
GPS Longitude |
latitude |
Float |
GPS Latitude |
voltage1 |
decimal |
Last report voltage in millivolts. |
temp1 |
Int32 |
Temperature measurement 1. For DeviceTypeID between 1 and 5 this is in Kelvin. For DeviceTypeID 14 or 15 this is in celsius. |
GPS_isCellTower |
Boolean |
If "false", then the latitude and longitude were calculated by GPS satellite signals. If "true" then cell-trilateration was used (much less accurate). |
GPS_speed |
Int32 |
Speed as calculated by GPS in MPH |
GPS_heading |
Int32 |
Heading as calculated by GPS |
6. API Request - Get Reporting Frequency Options for Device
- The reporting frequency options may vary based upon subscription level and device type.
- If all of your devices have the same subscription level and DeviceTypeID, it is safe to assume they all have access to the same reporting frequencies.
Sample request
HTTPS Post to https://api.charterup.com/api/v2/ with the following JSON Payload:
{
"commandstring": "get_reporting_frequencies",
"identifier": "Insert_My_DeviceID_Or_IMEI",
"token": "Insert_My_API_Key"
}
JSON Details
commandstring |
String |
Requested API Command |
identifier |
String |
Device's IMEI or DeviceID |
token |
String |
Your API Key |
Sample Response
{
"CommandString":"get_reporting_frequencies",
"timestamp":"10/25/2019 15:55:33",
"rate_limit_stats":"10sec_rate:1/20 1min_rate:1/60 1hour_rate:5/130",
"data":[
{
"ConfigID":161,
"ConfigName":"Basic",
"ConfigDesc":"Basic: 1-hour moving, daily check-in",
"ProductID": "37"
}
]
}
JSON Details
commandstring |
String |
Requested API Command |
timestamp |
String |
DateTime (UTC) of server response. |
data[] |
Array |
List of reporting frequency options (object type: Reporting Freqency object, see below) |
Reporting Frequency JSON Details
ConfigID |
Int32 |
Unique identifier for the reporting frequency option. |
ConfigName |
String |
Short name for the reporting frequency |
ConfigDesc |
String |
Extended description of the reporting frequency |
ProductID |
Int32 |
Identifier of the Product tied to this reporting frequency |
7. API Request - Get Organizations
- Returns an array of child organizations for the current organization in addition to details of the current organization
Sample request
HTTPS Post to https://api.charterup.com/api/v2/ with the following JSON Payload:
{
"commandstring": "get_orgs",
"token": "Insert_My_API_Key",
"identifier": "Insert_My_OrgID"
}
JSON Details
commandstring |
String |
Requested API Command |
identifier |
String |
Target OrgID |
token |
String |
Your API Key |
Sample Response
{
"CommandString": "get_orgs",
"timestamp": "10/01/2020 14:47:57",
"rate_limit_stats": "10sec_rate:1/20 1min_rate:1/60 1hour_rate:10/130",
"data": [{
"ChildOrgs": [
{
"OrgID": 7012,
"ParentOrgID": 7005,
"Name": "Child Org 1",
"DeviceCount": 43,
"DeviceGroupCount": 3,
"OrgCount": 2,
"UserCount": 15
},
{
"OrgID": 7013,
"ParentOrgID": 7005,
"Name": "Child Org 2",
"DeviceCount": 12,
"DeviceGroupCount": 0,
"OrgCount": 0,
"UserCount": 1
}
],
"CurrentOrg": {
"OrgID": 7005,
"ParentOrgID": -1,
"Name": "Parent Org",
"DeviceCount": 55,
"DeviceGroupCount": 3,
"OrgCount": 2,
"UserCount": 5
}
}]
}
JSON Details
commandstring |
String |
Requested API Command |
ChildOrgs |
Array |
Array of Org objects representing all organizations whose ParentOrgID is the current OrgID |
CurrentOrg |
Org |
Single Org object detailing the current Organization |
8. API Request - Get Device Groups
- Returns an array of device groups for the current organization
Sample request
HTTPS Post to https://api.charterup.com/api/v2/ with the following JSON Payload:
{
"commandstring": "get_device_groups",
"token": "Insert_My_API_Key",
"identifier": "Insert_My_OrgID"
}
JSON Details
commandstring |
String |
Requested API Command |
identifier |
String |
Target OrgID |
token |
String |
Your API Key |
Sample Response
{
"CommandString": "get_device_groups",
"timestamp": "10/01/2020 14:43:51",
"rate_limit_stats": "10sec_rate:1/20 1min_rate:1/60 1hour_rate:10/130",
"data": [{
"DeviceGroups": [
{
"DeviceGroupID": -1,
"Name": "Unassigned Devices",
"OrgID": 7005,
"AssignedToOrgID": -1,
"AssignedToOrgName": "",
"DeviceCount": 72
},
{
"DeviceGroupID": 22107,
"Name": "Devices for ChildOrg1",
"OrgID": 7005,
"AssignedToOrgID": 7012,
"AssignedToOrgName": "Child Org 1",
"DeviceCount": 43
}
]
}]
}
JSON Details
commandstring |
String |
Requested API Command |
DeviceGroups |
Array |
Array of Device Group objects representing all device groups within the current org. Note, when applicable, a special virtual device group will be included detailing the number of devices that reside outside of an actual device group. This device group will be termed "Unassigned Devices" and will carry a DeviceGroupID of -1. |
9. API Request - Get Device Group Devices
- Returns an array of devices within the target device group as well as target device group details.
Sample request
HTTPS Post to https://api.charterup.com/api/v2/ with the following JSON Payload:
{
"commandstring": "get_device_group",
"token": "Insert_My_API_Key",
"identifier": "Insert_My_DeviceGroupID"
}
JSON Details
commandstring |
String |
Requested API Command |
identifier |
String |
Target DeviceGroupID |
token |
String |
Your API Key |
Sample Response
{
"CommandString": "get_device_group",
"timestamp": "10/01/2020 14:43:51",
"rate_limit_stats": "10sec_rate:1/20 1min_rate:1/60 1hour_rate:10/130",
"data": [{
"DeviceGroupDevices": [
{
"DeviceID": 10019,
"Label": "Plow17",
"ConsumerKey": "TEP977",
"IMEI": "015766091014287",
"lastReportTime": "2020-10-01T17:06:34.96",
"lastReportGPSIsCellTower": false,
"lastReportLatitude": 36.177322,
"lastReportLongitude": -88.312127,
"lastReportUpdateTime": "2020-10-01T17:06:34.96",
"lastReportVoltage": 4113
},
{
...
}
],
"DeviceGroupDetails": [
{
"DeviceGroupID": 22107,
"Name": "Devices for ChildOrg1",
"OrgID": 7005,
"AssignedToOrgID": 7012,
"AssignedToOrgName": "Child Org 1",
"DeviceCount": 43
}
]
}]
}
JSON Details
commandstring |
String |
Requested API Command |
DeviceGroupDevices |
Array |
Array of simplified version of device object. Represents all devices contained within the target Device Group. |
DeviceGroupDetails |
Array (Length = 1) |
Array containing a single Device Group object detailing the target device group. |
10. API Request - Set reporting frequency for device
- Use the get_reporting_Frequencies command to determine available reporting frequencies/configIDs for the device.
- If all of your devices have the same subscription level and DeviceTypeID, it is safe to assume they all have access to the same reporting frequencies.
- When you set a reporting frequency with this API command, it queues up a request to change the reporting frequency.
- The next time the device reports in, it will ask the system "Are there any requested reporting frequency changes for me?"
- There may only be one pending frequency change at a time. Each new "set" command overwrites the previous.
- You may utilize the get_device command to see the pending reporting frequency.
- You may also use that command to determine when the reporting frequency is not longer pending (Pending will disappear and the current config information will contain the new reporting frequency)
- The words "Config" and "Reporting Frequency" are typically used interchangeably in this ecosystem.
- Once you identify the ConfigIDs available to your devices of a particular DeviceTypeID, you should not need to query get_reporting_frequencies to verify. The available configs would only really change upon reshuffling of your organization/devices or upon modifying your subscription levels.
Sample request
HTTPS Post to https://api.charterup.com/api/v2/ with the following JSON Payload:
{
"commandstring": "set_reporting_frequency",
"identifier": "Insert_My_DeviceID_Or_IMEI",
"ConfigID": "Insert_Desired_ConfigID",
"token": "Insert_My_API_Key"
}
JSON Details
commandstring |
String |
Requested API Command |
identifier |
String |
Device's IMEI or DeviceID |
ConfigID |
String |
A valid ConfigID (reporting freq) for the device |
token |
String |
Your API Key |
Sample Response
{
"CommandString":"get_reporting_frequencies",
"timestamp":"10/25/2019 15:55:33",
"rate_limit_stats":"10sec_rate:1/20 1min_rate:1/60 1hour_rate:5/130",
"message":"success"
}
JSON Details
commandstring |
String |
Requested API Command |
timestamp |
String |
DateTime (UTC) of server response. |
message |
String |
This will be "success" or "Success" if successful. Anything else indicates an error. The message may include helpful information depending upon the type of error. |
Appendix 1 - API Datastructures
A1.1 Device object
deviceId |
Int32 |
Device identifier |
OrgID |
Int32 |
Organization identifier |
imsi |
Int64 |
International Mobile Subscriber Identity |
iccid |
String |
Integrated circuit card identifier |
imei |
String |
International Mobile Station Equipment Identity |
serviceProvider |
String |
Service provider |
lastIP |
String |
Last IP address |
lastReportTime |
Int64 |
When the last report was generated by the device. Format: MM/dd/yyyy HH:mm:ss |
lastReportGPSIsCellTower |
Bool |
False: GPS Satellites were used to calculate position (very accurate). True: Cell tower information was used to calculate the position. May be off by up to a mile. |
lastReportLatitude |
decimal |
Last report latitude. |
lastReportLongitude |
decimal |
Last report longitude. |
lastReportReceivedTime |
Int64 |
When the last report was received by the server. Format: MM/dd/yyyy HH:mm:ss |
lastReportVoltage |
decimal |
Last report voltage in millivolts. |
customerLabel |
String |
Customer label |
consumerLabel |
String |
Consumer label |
consumerKey |
String |
Consumer key (product key) |
customerDesc |
String |
Customer description |
consumerDesc |
String |
Consumer description |
firmwareVersion |
String |
Firmware version |
serviceHours |
Float |
Service hours |
serviceHours_Date |
Int64 |
Service hours datetime. Format: MM/dd/yyyy HH:mm:ss |
serviceMileage |
Float |
Service mileage |
serviceMileage_Date |
Int64 |
Service mileage datetime. Format: MM/dd/yyyy HH:mm:ss |
serviceHours_Start |
Float |
Service hours start |
serviceMileage_Start |
Float |
Service mileage start |
serviceMileage_Mode |
Int32 |
Service mileage mode |
Image_URL |
string |
Image attached to tracker. If none is attached, then the value will be "". You may replace ".jpg" with "_thumb.jpg" to utilize a thumbnail version of the image. Sample value: "https://vtx-images.s3.amazonaws.com/vqam/custom/device-images/22901-0d6a87b5-c16e-4c47-adf1-0a290289ea73.jpg". |
ProductID |
Int32 |
Product identifier |
DeviceTypeId |
Int32 |
Device Type identifier |
A1.2 Report object
reportId |
Int32 |
Report identifier |
deviceId |
Int32 |
Device identifier |
iccid |
String |
Integrated circuit card identifier |
imei |
String |
International Mobile Station Equipment Identity |
receivedDate |
String |
UTC Datetime that the server received the device report. Format: MM/dd/yyyy HH:mm:ss |
updateTime |
String |
UTC Datetime that the device submitted the report. Format: MM/dd/yyyy HH:mm:ss |
longitude |
Float |
GPS Longitude |
latitude |
Float |
GPS Latitude |
voltage1 |
Int32 |
Battery voltage 1 |
voltage2 |
Int32 |
Battery voltage 2 |
temp1 |
Int32 |
Temperature measurement 1. For DeviceTypeID between 1 and 5 this is in Kelvin. For DeviceTypeID 14 or 15 this is in celsius. |
temp2 |
Int32 |
Temperature measurement 2 |
GPS_isCellTower |
Boolean |
Was GPS position calculated by cell tower trilateration |
GPS_speed |
Int32 |
Speed as calculated by GPS in MPH |
GPS_heading |
Int32 |
Heading as calculated by GPS |
GPS_satellites |
Int32 |
Number of satellites used in GPS position |
GPS_altitude |
Int32 |
Not used |
GPS_HDOP |
Float |
GPS precision |
rssi |
Int32 |
Cell reception strength on primary tower |
input0 |
Boolean |
Input value |
input1 |
Boolean |
Input value |
input2 |
Boolean |
Input value |
input3 |
Boolean |
Input value |
input4 |
Boolean |
Input value |
lastIP |
String |
Last IP address used by device |
WX_temp |
Int32 |
Weather service temperature |
WX_windSpeed |
Int32 |
Weather service wind speed |
WX_windGust |
Int32 |
Weather service wind gust |
WX_relativeHumidity |
Int32 |
Weather service relative humidity |
WX_pressure |
Float |
Weather service pressure |
WX_dewpoint |
Int32 |
Weather service dewpoint |
WX_icon |
String |
Weather service icon |
WX_areaLocation |
String |
Weather service area |
WX_link |
String |
Weather service link |
WX_desc |
String |
Weather service description |
WX_type |
Int32 |
Weather service provider |
WX_success |
Boolean |
Weather service success |
p0 |
Int32 |
Parameter value |
p1 |
Int32 |
Parameter value |
p2 |
Int32 |
Parameter value |
p3 |
Int32 |
Parameter value |
p4 |
Int32 |
Parameter value |
p5 |
Int32 |
Parameter value |
p6 |
Int32 |
Parameter value |
p7 |
Int32 |
Parameter value |
p8 |
Int32 |
Parameter value |
p9 |
Int32 |
Parameter value |
p10 |
Int32 |
Parameter value |
p11 |
Int32 |
Parameter value |
p12 |
Int32 |
Parameter value |
p13 |
Int32 |
Parameter value |
p14 |
Int32 |
Parameter value |
p15 |
Int32 |
Parameter value |
p16 |
Int32 |
Parameter value |
p17 |
Int32 |
Parameter value |
p18 |
Int32 |
Parameter value |
p19 |
Int32 |
Parameter value |
p20 |
Int32 |
Parameter value |
p21 |
Int32 |
Parameter value |
p22 |
Int32 |
Parameter value |
p23 |
Int32 |
Parameter value |
p24 |
Int32 |
Parameter value |
cellAccuracy |
Float |
Cell tower trilateration accuracy (meters) |
cellTower1 |
Cell tower |
Null / Cell tower 1 |
cellTower2 |
Cell tower |
Null / Cell tower 2 |
cellTower3 |
Cell tower |
Null / Cell tower 3 |
cellTower4 |
Cell tower |
Null / Cell tower 4 |
cellTower5 |
Cell tower |
Null / Cell tower 5 |
cellTower6 |
Cell tower |
Null / Cell tower 6 |
cellTower7 |
Cell tower |
Null / Cell tower 7 |
cellTower8 |
Cell tower |
Null / Cell tower 8 |
firmwareVersion |
String |
Firmware version |
TZ_dstOffset |
Int32 |
Timezone DST offset |
TZ_rawOffset |
Int32 |
Timezone raw offset |
TZ_timeZoneId |
String |
Timezone identifier |
TZ_timeZoneName |
String |
Timezone name |
TZ_status |
String |
Timezone service status |
hasAlert_GeoEntry |
Boolean |
Geozone alert on entry |
hasAlert_GeoExit |
Boolean |
Geozone alert on exit |
A1.3 Cell tower object
cid |
Int64 |
Cell tower identifier (CID) |
lac |
Int32 |
Location area code (LAC) |
mcc |
Int32 |
Mobile country code (MCC) |
mnc |
Int32 |
Mobile network code (MNC) |
rssi |
Int32 |
Cell tower signal strength (RSSI) |
A1.4 Core Report object
reportId |
Int32 |
Report identifier |
deviceId |
Int32 |
Device identifier |
iccid |
String |
Integrated circuit card identifier |
imei |
String |
International Mobile Station Equipment Identity |
receivedDate |
String |
UTC Datetime that the server received the device report. Format: MM/dd/yyyy HH:mm:ss |
updateTime |
String |
UTC Datetime that the device submitted the report. Format: MM/dd/yyyy HH:mm:ss |
longitude |
Float |
GPS Longitude |
latitude |
Float |
GPS Latitude |
voltage1 |
decimal |
Last report voltage in millivolts. |
GPS_isCellTower |
Boolean |
If "false", then the latitude and longitude were calculated by GPS satellite signals. If "true" then cell-trilateration was used (much less accurate). |
GPS_speed |
Int32 |
Speed as calculated by GPS in MPH |
GPS_heading |
Int32 |
Heading as calculated by GPS |
A1.5 Reporting Frequency Object
ConfigID |
Int32 |
Unique identifier for the reporting frequency option. |
ConfigName |
String |
Short name for the reporting frequency |
ConfigDesc |
String |
Extended description of the reporting frequency |
A1.6 Org Object
OrgID |
Int32 |
Unique Identifier. |
ParentOrgID |
Int32 |
OrgID of Parent Org, may be "-1" if not-applicable in case of top-level organization. |
Name |
String |
Org Name |
DeviceCount |
Int32 |
Number of devices assigned to this organization. |
DeviceGroupCount |
Int32 |
Number of device groups created within this organization. |
OrgCount |
Int32 |
Number of children organizations owned by this organization. |
UserCount |
Int32 |
Number of user accounts created within this organization. |
A1.7 Device Group Object
DeviceGroupID |
Int32 |
Unique Identifier. |
Name |
String |
Device Group Name. |
OrgID |
Int32 |
OrgID of organization which owns this Device Group. |
AssignedToOrgID |
Int32 |
OrgID of child org which this device group is assigned to - a common value is null |
AssignedToOrgName |
String |
Org Name of child org which this device group is assigned to - a common value is null |
DeviceCount |
Int32 |
Number of devices within this device group. |
Appendix 2 - PHP CURL Example
<?php
$API_KEY = "YOUR_API_KEY";
$API_URL = 'https://api.charterup.com/api/v2/';
// Create POST JSON
$data = [
'commandstring' => 'validate_api_key',
'token' => $API_KEY,
];
// Sets our options array so we can assign them all at once
$options = [
CURLOPT_URL => $API_URL,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($data),
];
// Prepare CURL
$curl = curl_init();
curl_setopt_array($curl, $options);
// Execute POST and process results
$results = curl_exec($curl);
$results_array = json_decode($results);
print_r($results);
curl_close($curl);
?>
Appendix 3 - API Rate Limits
To help prevent strain on the servers, the API imposes rate limits per organization for all issued API keys. The default rate limits are as follows:
- 20 requests per 10 seconds
- 60 requests per minute
- 130 requests per hour
Request Multiplier for computationally-expensive API commands:
The get_reports_single_device command may result in a modified rate-limit request counter. Examples:
- The request carries a multiplier: Ceiling(Results Returned / 1,000)
- If the request returns <= 1000 records -- this counts a 1 request in the rate limit system
- If the request returns <= 2000 records -- this counts as 2 requests in the rate limit system
- If the request returns <= 5000 records -- this counts as 5 requests in the rate limit system
The get_reports_all_devices command may result in a modified rate-limit request counter. Examples:
- The request carries a multiplier: Ceiling(Results Returned / 100)
- If the request returns <= 100 records -- this counts a 1 request in the rate limit system
- If the request returns <= 500 records -- this counts as 5 requests in the rate limit system
The 10-second rate limit does not apply to individual multiplied requests. For example: A request for 3,000 records, valued at 3 requests, will succeed so long as it occurs in a window where the minutely or hourly rate limits are not exceeded.
If the rate limit is temporarily exceeded, the API will return an error message describing the rate limit in question.
Staying Under the Limit
There are a few different ways to reduce the number of calls your application is making in a short period of time. The primary method used by our customers is to poll the API for reports once hourly or once daily. Example:
- Retrieve reports for ALL devices from between 5/13/19 11:00:00 and 5/13/19 12:00:00
- Then, in one hour, Retrieve reports for ALL devices from between 5/13/19 12:00:00 and 5/13/19 13:00:00
- Then, in one hour, Retrieve reports for ALL devices from between 5/13/19 13:00:00 and 5/13/19 14:00:00
- And so on...
- You may wish to (A) cache reports in your database system so that you never have to retrieve a report a second time and (B) keep track of the date of the latest report that you have received -- you may use that as the start-date of your next API request's filter set.
Also note that key "last report" fields are cached in the get_devices records -- GPS_IsCellTower (was the position calculated via cell-trilateration?), latitude, longitude, received time, generated time, and voltage. Many customers find that polling the get_devices API endpoint is sufficient for their purposes due to the presence of the cached last-report location data.
Longer term, we will offer webhooks where our system will push data to your system.
Other options
If your use case doesn't allow you to utilize limited polling or otherwise conflicts with our rate limits, reach out to our support team. We may be able to provide other suggestions, or pass on your use case to our engineering team for consideration.
Sample rate-limit-exceeded response
{
"CommandString": "get_devices",
"timestamp": "07/12/2019 13:31:47",
"rate_limit_stats": "10sec_rate:21/20 1min_rate:32/60 1hour_rate:44/130",
"message": "Rate Limit Exceeded: 10sec_ratelimit_exceeded:21/20 "
}