Geoforce Asset API Overview

The Asset API is a RESTful pull API providing a snapshot of all Assets in JSON format from the Geoforce platform (app.geoforce.com).

Access

Access User Settings
1. Log in at https://app.geoforce.com
2. Click Setup in the left-hand menu
3. Click the Users tab
4. Click the user’s email address
5. Open the API INTEGRATIONS tab
Create a "Geoforce Core Services" API token
1. Under New API Key, select Geoforce Core Services API from the dropdown
2. Under Asset API, select the necessary scope permission
3. Click Create Key
4. Your JSON Web Token will be generated and added to the list of API Keys
5. Click Show under the Key and Secret columns. This Key and Secret combo is required to obtain an Asset API JWT Token (see below).

Data Included

Asset Attributes: Name, ID, Make, Model, Serial Number,
Asset Status: Latest Location, Locations Nearby, Street Address, Timestamp
Telemetry: ERT, Ignition, Idle time, Line Voltage, Speed, Odometer, Speed, Heading
Filtering: By date range, Asset IDs, Flag, device assignment

Getting Started

Generate a "Geoforce Core Services" API Key and Secret for a user in the Geoforce Platform (See "Access" above)
Obtain an Asset API JWT Token (token expires in 1 hour)
- POST to the User-Org API endpoint, Username = Your Key, Password = Your Secret, and Scope = asset_api:read. Details in the User-Org API documentation
Make a POST request to the Asset API endpoint using this JWT Token:
```
POST https://asset.api.geoforce.com/v1/query
```
Use query parameters to refine data (e.g., date range, asset IDs)
Determine pull frequency for your integration
Note: The legacy hostname asset-api.geoforce.com is not recommended for new implementations and will be obsoleted by the end of 2027. New integrations should use the gateway URL (https://api.geoforce.com/asset).

Documentation

Please refer to Geoforce Asset API Documentation

Elements of a Request

Filters (optional)

Filters let you limit which assets are returned.

ids (number[])

Only include assets whose IDs are in the list.

flagColors (string[], default: null)

Only include assets with one of these colors: red, yellow, green, black.

lastReportedAt (object, default: null) (the timestamp of the latest reading, including non-location readings)
Filter by the time the asset last sent a reading:

from (ISO 8601 date/time) → only include assets that reported after this time
to (ISO 8601 date/time) → only include assets that reported before this time
hasNeverReported (boolean, default: false) → if true, ignore from/to and only return assets that have never reported

hasAssignedDevice (boolean, default: null)

true: only assets with a device assigned
false: only assets without a device
null: all assets

Include (optional)

Include controls which fields are shown in the response.

Examples:

name (the Asset Name as configured in the application)
externalAssetId (the Asset ID as configured in the application)
latestReading (the latest location reading)
latestReading.coordinates (the coordinates of the latest location reading)
latestReading.reportedAt (the timestamp of the latest location reading)
device (the ESN and the internal ID of the Device installed on the Asset)
- deviceId (deprecated, do not use)
accountId (the Geoforce unique ID of the Account)
make, model, serialNumber
flagColor, markerColor
nearestLocationName, enteredNearestLocationAt
nearbyLocations (the full list of all named locations, geofences, well sites, etc. mached to the latest reading)
- Locations from the following layers also be returned if these layers are enabled for the account
  - DrillingInfo Rigs
  - US Wells
updatedAt (only has a value if the asset was updated after the release date; otherwise null)

Pagination

Pagination controls how many results you get and which page is returned.

page (number, default: 1)

Which page of results to return.

perPage (number, default: 50)

Number of results per page.

Units

Units define the measurement system used in the response.

units (string, default: metric)

Measurement system for returned values.
Options: metric or imperial.

Sample Request

{
  "filters": {
    "ids": [],
    "flagColors": [],
    "lastReportedAt": {
      "from": "2025-01-20T20:28:33.000Z",
      "to": null,
      "hasNeverReported":false
    },
    "hasAssignedDevice": true
  },
  "include": [
    "device",
    "latestReading",
    "latestReading.coordinates",
    "latestReading.reportedAt",
    "accountId",
    "name",
    "make",
    "model",
    "serialNumber",
    "externalAssetId",
    "flagColor",
    "nearestLocationName",
    "enteredNearestLocationAt",
    "updatedAt",
    "nearbyLocations"
  ],
  "page": 2,
  "perPage": 20,
  "units": "metric"
}

Elements of a Response

total

Shows the total number of assets returned by the query.

Data type: number
Used for paging → total / perPage = number of pages

allPages

Gives the total number of pages available.

Data type: number

data

Contains the actual results of the query.

Data type: object

Asset fields inside `data`

id (number) → ID of the asset (Geoforce internal ID, see also below - externalAssetId)
device (object) → Assigned device details (replaces deprecated deviceId)
- id (number) → Device ID (Geoforce internal ID)
- esn (string) → Device ESN (electronic serial number)
accountId (number) → ID of the account the asset belongs to
name (string) → Name given to the asset (the Asset Name as configured in the application)
make (string) → Manufacturer of the asset
model (string) → Manufacturer’s model name or number
serialNumber (string) → Serial number of the asset
externalAssetId (string) → Customer identifier for the asset (the Asset ID as configured in the application)
flagColor (string) → Flag assigned to the asset (red, green, yellow)
markerColor (string) → Pin color used on the map
nearestLocationName (string) → Most specific location that matches the last reading
nearbyLocations (the full list of all named locations, geofences, well sites, etc. mached to the latest reading)
- Locations from the following layers also be returned if these layers are enabled for the account
  - DrillingInfo Rigs
  - US Wells
enteredNearestLocationAt (date) → When the asset last entered the location of its last reading
updatedAt (date) → When the asset was last edited, such as name/id changes. Default is null until the asset changes, then shows a timestamp. This field is unrealted to the asset's location and readings.

latestReading (object)

Holds the most recent reading from the assigned device.

coordinates (object) → GPS position
- latitude (number)
- longitude (number)
reportedAt (date) → When the device last reported
engineTelemetry (object) → Engine status data
- ignition (boolean?) → Engine on/off
- idling (boolean) → Whether engine is idling
- idleTime (object) → How long engine has idled (value + unit: h, m, s)
- adjIdleTime (object) → Adjusted idle time (value + unit)
- engineRuntime (object) → How long engine has been running (value + unit)
- adjEngineRuntime (object) → Adjusted runtime (value + unit)
gpsOdometer (object) → GPS-calculated odometer (value + km)
adjGpsOdometer (object) → Adjusted GPS odometer (value + km)
movement (object) → Movement data
- heading (number) → Direction of movement in degrees (0=N, 90=E, 180=S, 270=W, -1=unknown)
- inMotionTime (object) → Total time asset has been moving (value + h)
- adjInMotionTime (object) → Adjusted motion time (value + h)
- speed (object) → Current speed (value + km/h)
power (object) → Power data
- lineVoltage (object) → Voltage reported from the connected equipment (value + mV)
vibAccum (object) → Total vibration time detected (value + h)
stopped (boolean) → Indicates whether the asset is currently not moving or running

Sample Response, GT2 device

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

{
    "total": 999,
    "allPages": 50,
    "page": 2,
    "perPage": 20,
    "data": [
        {
            "id": 785283,
            "device": {
                "id": 498899,
                "esn": "2-3333333"
            },
            "latestReading": {
                "movement": {
                    "heading": "0",
                    "speed": {
                        "value": 0,
                        "unit": "km/h"
                    }
                },
                "stopped": "true",
                "reportedAt": "2025-01-21T22:35:09.000Z",
                "coordinates": {
                    "latitude": 40.95623731613159,
                    "longitude": -83.35436582565308
                }
            },
            "accountId": 9035,
            "name": "NLRX009012",
            "make": null,
            "model": null,
            "serialNumber": null,
            "externalAssetId": "70037620",
            "flagColor": null,
            "nearestLocationName": "Carey",
            "enteredNearestLocationAt": "2025-01-17T12:10:01.000Z",
            "updatedAt": null,
            "nearbyLocations": [
                {
                    "name": "Carey"
                },
                {
                    "name": "Akron Canton and Youngstown RR"
                }
            ]
        },
...

Error Handling

Below are common issues, their status codes, and returned messages.

Invalid date range

Status Code: 400
Message: filters.lastReportedAt.to must be after from
The from date must be earlier than the to date.

Unsupported property key

Status Code: 400
Message: [parentKey].property [property] should not exist
Occurs when a property key is not supported. Applies to both parent and child keys (e.g., hasNeverReported).

Unsupported value in include array

Status Code: 400
Message: each value in include must be one of the following values: accountId, deviceId, externalAssetId, flagColor, latestReading, make, model, name, nearestLocationName, serialNumber
Happens when an invalid field name is passed in include.

Missing perPage for paginated request

Status Code: 400
Message: perPage is required for this request
perPage must be provided when the request requires pagination.

perPage exceeds limit

Status Code: 400
Message: perPage must not be greater than 1000
The perPage parameter cannot exceed 1000.

Unsupported value for units

Status Code: 400
Message: units must be one of the following values: metric, imperial
Only metric and imperial are allowed for units.

Invalid array value type

Status Code: 400
Message: [parentKey].each value in [property] must be a [valueType] conforming to the specified constraints
Occurs when an array contains an unsupported value type. Example: {groups: [“3”, 4, 5]}.

Invalid date format

Status Code: 400
Message: filters.lastReportedAt.[property] must be a valid ISO 8601 date string
lastReportedAt.from and lastReportedAt.to must be valid ISO 8601 dates (e.g., 2023-12-18T14:14:28.000Z).

Invalid or expired access token

Status Code: 401
Message: Unauthorized
The access token is missing, invalid, or expired.

Forbidden resource

Status Code: 403
Message: Forbidden resource
The user attempted to access a resource that is not visible.

Incorrect HTTP method

Status Code: 405
Message: Method is not allowed for this route. Please use POST /query instead.
The /assets/query endpoint must be called with POST, not GET.

Unknown server error

Status Code: 500
Message: Internal server error
A generic error occurred on the server.

Access

Data Included

Getting Started

Documentation

Elements of a Request

Filters (optional)

Include (optional)

Pagination

Units

Sample Request

Elements of a Response

total

page

allPages

data

Asset fields inside `data`

latestReading (object)

Sample Response, GT2 device

Error Handling

Invalid date range

Unsupported property key

Unsupported value in include array

Missing perPage for paginated request

perPage exceeds limit

Unsupported value for units

Invalid array value type

Invalid date format

Invalid or expired access token

Forbidden resource

Incorrect HTTP method

Unknown server error

Comments

Table of Contents

Access

Data Included​

Getting Started​

Documentation

Elements of a Request

Filters (optional)

Include (optional)

Pagination

Units

Sample Request

Elements of a Response

total

page

allPages

data

Asset fields inside data

latestReading (object)

Sample Response, GT2 device

Error Handling

Invalid date range

Unsupported property key

Unsupported value in include array

Missing perPage for paginated request

perPage exceeds limit

Unsupported value for units

Invalid array value type

Invalid date format

Invalid or expired access token

Forbidden resource

Incorrect HTTP method

Unknown server error

Related articles

Table of Contents

Data Included

Getting Started

Asset fields inside `data`