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.

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. Setup → Accounts → Click the customer account. At the end on the page click on Edit button.
2. Click on API Integrations tab
3. Give a custom name for the new API Key. Then click on Create Key button.
4. A new token will be created, enabled by default. To see the API key click View on the API key column. This key now is authorized to make GraphQL calls. To use it on Altair, click on Set Headers and add it as an Authorization header: “Authorization MY_GRAPHQL_TOKEN”

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:

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# 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})

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)

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.