What is GraphQL?

If you’re used to REST APIs, think of GraphQL as a more flexible way for apps to ask for information. With REST, you often have many different endpoints, and each one gives you a fixed set of data - sometimes more than you need, sometimes not enough. GraphQL changes this by giving you one endpoint where the client can simply ask for the exact pieces of data it wants, nothing extra. One way of describing it is like having a safe way to query the Telematics Guru database directly.
 

Why Would I Use the GraphQL Endpoint?
 

1. Filtering - Our existing REST endpoints return complete records even when you only need a small subset. With GraphQL, you can ask for exactly the assets that match your criteria. For example, only assets in department X or those with fewer than Y kilometres on the odometer.
    
2. Response Size - GraphQL lets you select the exact fields you want returned in the response, whereas our REST APIs give you a standard set of fields. Think of it as the difference between visiting a buffet on your own and selecting only your favourite foods versus having your grandmother fill the plate with every single item the buffet because she loves you.
    
3. Frequency - GraphQL is not rate-limited by number of calls alone like a traditional endpoint. Instead, limits are based on how complex your query is. Simple queries cost less, so you can check in with the server more often without hitting a limit. 
    
4. Simpler Integrations - With REST, gathering all of the information you need might means making multiple calls (one for the asset, another for its latest telemetry, another for its status, etc). GraphQL allows you to bundle all these into a single request. This reduces complexity in your code and makes integrations cleaner and easier to maintain.
    
5. Future-Proofing - As our platform evolves, GraphQL makes it easier to add new fields or relationships without breaking existing integrations. Clients only ask for what they need, so changes to the API are less disruptive. This means fewer surprises and smoother upgrades over time.

Documentation

To view documentation, first find your instance and then insert it into the url below:

https://api-<yourinstance>.telematics.guru/graphql/

This will take you to our hosted “Chilli Cream” GraphQL site, where you can actively experiment with GraphQL. 

You'll also need to generate an API key for TG for authentication purposes and so that your application will not rely on frequent regeneration of a 24-hour expiring token. 

What do I need to get Started?

The first thing you will want to do is to generate an API key for TG so that your application will not rely on frequent regeneration of a 24-hour expiring token. Once you have that, you will also need to determine your native Telematics Guru server. We have multiple servers worldwide and the best way to determine which one you are using is to take your usual URL (i.e. mytrackingcompany.telematics.guru) and conduct a ping test (for example: PING Test by WebSitePulse). This will show you the underlying server identity which will take the form of a region and a number (i.e. amer03). Armed with this, you can insert it into the url as per the below:

https://api-<yourinstancegoeshere>.telematics.guru/graphql/

This will take you to our hosted “Chilli Cream” GraphQL site.
 

GraphQl is merely a type of endpoint, designed to be used via your own custom code in a programming IDE or an analytics tool like Microsoft Power Query, but you can use our hosted site to test things out in a purpose-built environment.

Making Your First Query

Step 1 - Click on Create Document to open a screen where you can start building a query. 

Step 2 - Click on the Connection Settings cog-wheel in the top right-hand corner (you will also see your endpoint url). Switch to the Authorisation tab and choose Bearer. When new fields appear, paste your API Key (or bearer token generated from basic authentication) into the “Token” field, before clicking Apply. This authenticates you within the query builder.

Step 3 - Click on the Operation Builder button (symbol to the left of the word “Request”) and then click on the “+” plus icon that appears to create a New Query. Name your query something memorable, like “Alamo” or “5th-of-November”.

Step 4 - Expand your new query by clicking on it such that it reveals the different types of datapoints available. For your first query, we recommend retrieving a list of organisations that you have access to, including their organisationId. The organisationId is essential for all other queries. To do this, tick the levels as indicated in the diagram below - organisations (the “connection” level) and then the “nodes” of name and organisationId.

Step 5 - Run the query by clicking the big red Run button. Notice how the site has built a query for you in code - this is what you would use for a proper integration.
 

Step 6 - Your response will mirror the structure of your request, but with data. The organisationId returned from this particular query is required for every other query on the other types of records (for example: assets, events, trips). 

 This is the main method for structuring and receiving information.

Making Your Second Query

Armed with the organisationId for the organisation that holds information you wish to query you are now ready to gather additional types of information. For this example we will query assets,

Step 1 - As before, make a new query using the Create Query "+"icon and give it a unique name. This time, instead of expanding the list of options and picking “organisations” instead pick “assets”

Step 2 - Under Assets you will see an option called arguments which upon expansion will reveal an option entitled organisationId. Tick that option and you will see a new section in your request for organisation Id with a current value of “null”. Click into the editor with your cursor and replace the "null" into the organisationId that you got previously (i.e. “238”). 

Step 3 - Test this out by simply hitting “Run” and you should see the total number of assets for your organisation returned in the response box. Keep in mind that although the total is accurate, without pagination you will be limited in the number of records that can actually be returned when you start trying to get information for individual assets.

Step 4 - You finally get to experience some business value! Expand the “nodes” option and pick from the buffet of excellent fields for your assets. You will notice that some fields expand and have options under them. In particular - the name of the current location for any given asset is actually the name of a geofence, and therefore you will need to expand that to get the fenceName if you want the address. When you are done you may Run again to see the results.

Step 5 - Now to experiment with filtering. Click the same arguments box that you did to expose the organisationId and this time expand where. You will see the same options as previously greeted you under nodes. This time you can use them to filter your results with the conditions under each option. For example:

where: { name: { contains: "gen" } }

This would return all assets that have “gen” in the name, like “generator” or “general purpose truck #2”. Using multiple filters and pagination you can get very specific results!

Next Steps

Now that you have a working query, transpose it into your preferred coding IDE and give it a try!