CharterUP Enterprise Tracking API

 API Documentation

Contents

1. Retrieve your API Key

  1. Visit https://app.charterup.com/
  2. Log in
  3. Click your username in the top right
  4. 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
    }]
}

JSON Details

commandstring String Requested API Command
timestamp String DateTime (UTC) of server response.
data[] Array List of reports (object type: Core Report object, see below)

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
    }]
}

JSON Details

commandstring String Requested API Command
timestamp String DateTime (UTC) of server response.
data[] Array List of reports (object type: Core Report object, see below)

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