Geoforce Reading API Overview​

The Reading API is a RESTful pull API providing all device readings in JSON format from the Geoforce platform​ (app.geoforce.com).

Data Included​

• Device Readings: ESN, Latitude/Longitude, Timestamp, Asset​
• Device-Specific Fields: Battery Level, Engine Run Time, Engine Start/Stop, etc.​
• Filtering: By date range and device IDs (optional)​

Getting Started​

• Generate a JSON Web Token (JWT) for a user in the Geoforce Platform​ 
  • Refer to https://readings.geoforce.com/ for details

• Make a GET request:​

  GET https://readings.geoforce.com/readings?token=your_token_id_here​_for_testing_only

• Use query parameters to refine data (e.g., date range, device IDs)​
• Determine pull frequency for your integration​
• For production, place the token in the header instead of the URL

Reading API Data Retention

The Reading API retains all readings for 40 days.

Documentation

https://readings.geoforce.com/

Limitations

• Max response size: 1000 readings
• There's no pagination

• 40 days of data retention

Sample Request

GET https://readings.geoforce.com/readings?​
from=2025-02-05T02:00:00Z&​
to=2025-02-05T03:00:00Z&​
time_series=received&​
token=your_token_id_here​_for_testing_only

Sample Response, GT2 device

Please note that the response structure could vary depending on the device type.

{​
    "readings": [​
        {​
            "esn": "70057155",​
            "asset": {​
                "id": 857173,​
                "name": "Cat Loader 123",​
                "number": "70057155",​
                "account": {​
                    "name": "Geoforce, Inc"​
                }​
            },​
            "status": {​
                "speed": "0.0",​
                "input1": "false",​
                "input2": "false",​
                "heading": "0",​
                "stopped": "true",​
                "ignition": "false",​
                "message_type": "Interval Location",​
                "battery_status": "true"​
            },​
            "payload": "0x015bc5078dcc18921f00",​
            "position": {​
                "type": "Point",​
                "coordinates": [​
                    -77.9900312423706,​
                    -42.46363615989685​
                ]​
            },​
            "timestamp": "2025-02-05T01:51:50.000Z",​
            "gps_odometer": null,​
            "political_area": null,​
            "received": "2025-02-05T01:52:01.854Z"​
        }, ...​
​