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.
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 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 "
}