Geoforce GraphQL API Overview​ ​

Use the GraphQL pull API to get data points on devices and readings in a single query from the Geoforce platform​ (app.geoforce.com).

Data Available​

• Device Readings: ESN, Latitude/Longitude, Timestamp, other device-specific attributes…​
• Devices: ESN, Latest Location, IMEI…​
• Users: Name, ID, Role, Email, …​
• Organization: Name, Description, ID, …​

Getting Started​

• Generate a GraphQL Token (JWT) in the Geoforce Platform.​
  • Setup / Accounts / Edit / API Integrations​
• Test in Altair ​
  • https://api.geoforce.com/altair/ ​
  • Set Header, Key = Authorization and Value = your_graphql_token​
• Refer to the documentation in Altair by clicking the "doc" button in the top right corner​
• Determine pull frequency for your integration​

Documentation

https://graphql.geoforce.com/

https://api.geoforce.com/altair

Code Sample - Fetching device battery level/status

 

Battery Level

Battery level (levelLabel) is an estimation based on typical device operating conditions. This property is only available with GT, and AT3 devices.  

Full (100% - 80%), High (80% - 60%), Medium (60% - 40%)
Fair (40%-20%), Replace (20%-0%)

“Full”, “High”, and “Medium” are mapped to “Good” in the Geoforce application UI.

Battery Condition

Battery Condition (condition) is available with AT2 devices.

Good (Battery is healthy), Replace (Battery is dead)

Fetching the latest battery information, state, and the assigned asset of all devices, with pagination

query getAllDevicesInfoPageOne {
  devices(
    first: 500 # up to 1000
  ) {
    totalCount # this count slows down the query, only use when needed
    pageInfo {
      endCursor # use this for pagination
      hasNextPage
    }
    nodes {
      esn
      state
      deviceModel {
        typeName
      }
      asset {
        id # backend Unique ID
        name # the Asset Name in Geoforce UI
        assetId # the Asset ID in Geoforce UI
      }
      latestReading {
        battery {
          condition # available with AT2 devices
          levelLabel # available with GT and AT3 devices
          timestamp
        }
        coordinates {
          latitude
          longitude
        }
        reportedAt
      }
    }
  }
}


query getAllDevicesInfoPageTwo {
  devices(
    first: 500
    after: "NTAw" # insert endCursor of the previous page here
  ) {
    # totalCount # this count slows down the query, only use when needed
    pageInfo {
      endCursor # use this for pagination
      hasNextPage
    }
    nodes {
      esn
      state
      deviceModel {
        typeName
      }
      asset {
        id # backend Unique ID
        name # the Asset Name in Geoforce UI
        assetId # the Asset ID in Geoforce UI
      }
      latestReading {
        battery {
          condition # available with AT2 devices
          levelLabel # available with GT and AT3 devices
          timestamp
        }
        coordinates {
          latitude
          longitude
        }
        reportedAt
      }
    }
  }
}

Fetching the latest battery information, state, and the assigned asset of devices that are active and has an assigned asset, with pagination

query getFilteredDevicesInfoPageOne {
  devices(
    first: 500 # up to 1000
    filter: {
      assigned: true
      state: active
    }
  ) {
    totalCount # this count slows down the query, only use when needed
    pageInfo {
      endCursor # use this for pagination
      hasNextPage
    }
    nodes {
      esn
      state
      deviceModel {
        typeName
      }
      asset {
        id # backend Unique ID
        name # the Asset Name in Geoforce UI
        assetId # the Asset ID in Geoforce UI
      }
      latestReading {
        battery {
          condition # available with AT2 devices
          levelLabel # available with GT and AT3 devices
          timestamp
        }
        coordinates {
          latitude
          longitude
        }
        reportedAt
      }
    }
  }
}

Fetching the latest battery information and the location of a single device

query getDevicesInfo {
  devices(filter: { esn: "2-3510463" }) {
    nodes {
      esn
      deviceModel {
        typeName
      }
      asset {
        name
      }
      latestReading {
        reportedAt
        battery {
          condition
          levelLabel
          timestamp
        }
        coordinates {
          latitude
          longitude
        }
      }
    }
  }
}