The Geoforce Platform

The Geoforce Platform is built on GraphQL, which is an API Query Language, and a server-side runtime for executing queries using a type system. These APIs allow our customers to access or update data within the Geoforce Platform. The benefit of this query language is allowing more specificity in the requests for information and to be more efficient when requesting large amounts of information.

More information about GraphQL can be found by clicking the GraphQL link in the header, which will take you to the GraphQL Foundation website. A great deal of information and other tools can be found there. Additionally, the Community link in the header will provide even more resources and an opportunity for you to connect with other developers worldwide that also use GraphQL in their own solutions.

 
Getting started is easy!

GraphQL Clients

To begin you will want a GraphQL client and need an authorization token. Geoforce provides a client that can be used via our online tools, though one can optionally use other GraphQL clients, both web-based and locally installed instances.

Altair is an open-source GraphQL Client that lets you debug GraphQL queries and implementations, available for multiple platforms including browsers like Safari, Chrome, & Firefox and all major operating systems. Geoforce provides an online implementation that also provides all online documentation of the available requests that can be made. The online implementation provided by Geoforce can be found at this link, or by clicking the Documentation & Altair Client link in the header. You can find more information or download your own local copy of Altair here.
GraphiQL is a popular lightweight and interactive in-browser GraphQL IDE that is built with React by the GraphQL Foundation. The GitHub implementation of it can be found here.
Postman is another API development platform that is quite popular among developers. Much like other API specific tools, Postman isn’t specifically built for GraphQL and is better suited for traditional REST APIs. However, the support for GraphQL has become a bit more sophisticated and robust in the latest iterations. Postman can be found here.

 

Authentication

To access the GraphQL API, you will need an API Authentication Token. This token can be created by an admin for your company with access to the core Geoforce software by following these instructions:

  1. Access user settings at https://app.geoforce.com/setup/users
  2. Click on the username that will accessing the API
  3. Click on the ‘Client Applications‘ tab
  4. Generate a GraphQL Web Token
    1. Inside the ‘Generate Key‘ section, select ‘GraphQL Web Token‘ from the dropdown
    2. Click the ‘Generate‘ button
    3. Your GraphQL Web Token will be generated and appended to the list of Client Applications
    4. Click on the ‘show’ link under the ‘Client ID‘ column. This key is your GraphQL Web Token that you will use on every request to the Readings API.

Using the Authentication Token

If you’re using the Altair client, you will use your API Authorization token by opening up the Headers section by opening the Headers modal in the Altair client as shown:

Next, enter “Authorization” as the Header Key and the API Token Key as the Header Value as shown.

Creating Queries using Altair

GraphQL commands are displayed in the documentation portion of the client.  Geoforce publishes the GraphQL schema in the standard format for clients to display. This can be found in Altair using the Docs button in the upper right of the Altair screen. The Docs button will display all necessary information relating to the available schema.

Users have the ability to review queries and mutations (updates), and can generate commands automatically. To create a device query, the user can select the “Add Query” button next to the device query to add the structured query:

Using Queries and Mutations

GraphQL has Queries and Mutations which allow you to get data and update data. Queries are getting data via GraphQL from the Geoforce Platform, while Mutations allow you to update data within the Geoforce Platform.

The GraphQL API accepts traditional http post requests in your language of choice.  This means that the API is compatible with most languages and existing tools. You only require the details (JSON Query) to be included in the request body. Here is an example of a curl request:

curl -g \

-X POST \

-H “Content-Type: application/json” \

-H “Authorization: [api_key]” \

-d ‘{“query”: “query getDevice{  device(esn: [device esn]){bluetoothMac  createdAt esn  hardwareVersion id updatedAt}}”}’ \

 

Coding Examples

Below are examples of how you can use the GraphQL Queries within your own application, though there may be other ways to accomplish integrating a GraphQL query as well. Additionally, GraphQL works with all major development languages that can make Rest API query and update requests.

C#

// C# Code example using RestSharp
RestClient GraphQLClient = new RestClient("https://api.geoforce.com/graphql");
// Add Body for GraphQL Request
  var RequestBody = @"
	query device_query
	{
		devices
		{
			nodes{esn createdAt}
			totalCount
		}
	}
	";
// Create Post Request - all GraphQL Requests will be post methods
RestRequest GraphQLRequest = new RestRequest(Method.POST);
// Add API Key to header
GraphQLRequest.AddHeader("Authorization", "your API key here");
GraphQLRequest.AddHeader("Content-Type","application/json");
// Add query to request body
GraphQLRequest.AddJsonBody(new{query = RequestBody }});
// Execute Request
IRestResponse GraphQLRequestResponse = GraphQLClient.Execute(GraphQLRequest);
Python
import requests q = """ { website(url: "https://api.geoforce.com/graphql") { device deviceID } } """ resp = requests.post("http://YourURL:5000/", params={'query': q})
Ruby

query_string = "
mutation createPost($postParams: PostInput!, $createdById: ID!){
  createPost(params: $postParams, createdById: $createdById) {
    id
    title
    createdBy { name }
  }
}
"

variables = {
  "postParams" => {
    "title" => "...",
    "body" => "..."
  },
  "createdById" => "5",
}

MySchema.execute(query_string, variables: variables)

JavaScript

query readings
{
 readings(filter:{from:"2022-01-15" to:"2022-01-20"} orderBy:{direction:desc field:reported_at})
 {
   nodes
    {
     reportedAt
     location{latitude longitude}
     device{esn}
   }
 }
}

 

 

All Query and Mutation Documentation

To access the Query and Mutation Documentation, and more easily create a query, you can use the Documentation we’ve provided within the online Altair GraphQL Client. To access this data, simply click the “Docs” in the upper right hand corner of the Altair client.