In the following sections, we will cover getting started with the RFT API. We will introduce basic terminology as well as how to quickly get started with prototyping and testing. Within our documentation, we state all Queries as well as the Schema we use for this API. Selecting a Query from the menu (under the "Queries" section) will show a brief description followed by an example request as well as an example response. The "Schema Definitions" section shows all types used by our schema with a description as well as fields and return types.

Host URL

All requests require a host url. Requests will be passed to the v3api.rhinofleettracking.com/graphql host URL.

Access Tokens

Access tokens will allow your application to access the RFT API. These tokens hold two main functions:

• They allow the user access to RFT data and information.
• They allow us to identify your application as well as the type of data you, as the user, is permitted to gain access to.

Obtaining A Token

If you are reading this, you most likey have been given a secret token to use with this API. However, if you do not have a secret token and are looking to utilize this API, please contact customer service to be provisioned a new secret token specific to you. ( customerservice@rhinofleettracking.com)

Using Your Provisioned Token

Once you have obtained a secret token. You will be able to start using the RFT API and all its features. To utilize your secret token when making a request, add the secret key to your request's header with the value you have been given (as a string). For example: headers: { secret: "<SECRET_TOKEN>"} For a more detailed description on how to make requests to our GraphQL API, visit our Getting Started with GraphQL section below. If you are familiar with the GraphQL query language and how it's used, you can quickly jump into prototyping by using the queries we provide to make requests in the GraphQL Playground we provide for you.

Prerequisites

Like many APIs, this GraphQL based API conforms to HTTP. Because of this, it works with any language that can make HTTP calls or has an HTTP library such as curl. Below is a short list of useful tools to assist in making these calls.

• curl - a command line tool used for data transfers
• Postman - a GUI based tool to quickly and easily send GraphQL requests
• Our Provided GraphQL Playground - Although this may be the easiest tool to get a feel for understanding and using this API's schema, this may not help with utilizing this API programatically. (You can read a more detailed description on how to use this in our Using the GraphQL Playground)

In the following examples, we will be using curl commands to request and retrieve data from the RFT API.

Making your First RFT API Call (using curl)

The following code can be copied and pasted into your terminal (replacing <YOUR_SECRET_TOKEN> with your actual token).

  curl --location --request POST 'https://v3api.rhinofleettracking.com/graphql' \
  --header 'secret: "<YOUR_SECRET_TOKEN>"' \
  --header 'Content-Type: application/json' \
  --data-raw '{"query":"query devicesQuery {\n  devices {\n    id\n    alias\n  }\n}","variables":{}}' | json_pp

Details of this command will be discussed below.

Structure

In general, when making a GraphQL call, there are a few commonalities across languages and uses that we should make apparent. - First, a GraphQL call is usually a POST request (always in our case). - This post request is sent to a host server; in our case, https://v3api.rhinofleettracking.com/graphql. - The request body consists of the GraphQL Query in its respective language/syntax. - Lastly, the data returned is in json format. In our case, we require a secret token for authentication, so this value is required in the request's header (as the value of secret).

GraphQL Query

The graphQL request body contains whats referred to as a "GraphQL Query". These Queries consist of types as well as the fields of those types required to request exactly what is needed by the user. Below is a formatted version of the query we called in the above curl command.

  query devicesQuery { // state we are using a GraphQL query within the brackets
    devices { // one of the provided queries for our API
      id // a field we chose to retrieve from this query
      alias // a field we chose to retrieve from this query
    }
  }

• For a specific list of the allowed query types, refer to the queries in the "Queries" section.

• For a list of the allowed field types, please visit the "Schema Definitions" section below.

  Wrapping Query Type

  Each Query consists of a query type that defines what general data we are wanting. In the above case, our query type used is devicesQuery. This wrapping is used to simply state, "I want to make a query request that I'm calling 'devicesQuery'".

  Schema Query Type

  Wrapped inside the the devicesQuery is the query type devices. This query type is defined within our schema and allows you to access data on the devices associated with your account. Placing this type in your request is what tells us which general data you are looking for.

  Query Fields

  Finally, wrapped within the requested query (In our case, the devices query) is the specific fields that you as a user will request. These fields consist of types (as well as nested types) that specifically tell the server exactly what you are wanting to recieve from the general query. In this case, we want to specifically obtain the id and alias for each device returned from the server. All possible fields for a given query/type are listed below in the "Schema Definitions" section.

For your convenience, we host a GraphQL Playground, allowing you to quickly test and prototype your queries. The quickest way to get started with the playground is to navigate to one of the queries we provide below such as "Devices". Simply click " Try it now" and you will automatically be taken to the playground and the query will be placed in the editor.

• Note that you will need to expand "HTTP HEADERS" at the bottom of the screen and place your secret token like so:

  {
  "secret": "<YOUR_SECRET_TOKEN>"
  }
  

• Also, if your query requires variables ("Devices" does not), you can simply copy and paste the example variables into the "QUERY VARIABLES" tab below the query and simply replace the values.

  {
  "begin": "<YOUR_VALUE>",
  "end": "<YOUR_VALUE>",
  "eventTypes": [
    "<YOUR_VALUE>"
  ],
  "deviceIds": [
    "<YOUR_VALUE>"
  ]
  }
  

Query Rate Limiting

There are limits to the amount of data that can be requested from the Rhino Fleet Tracking API based on both call counts as well as data size.

Call Count Limit

Currently, all queries are limitted to a 15 call per minute rate. Exceeding this limit will return the error message: "Rate Limit exceeded". If met with this error, simply wait a few seconds before requesting the same query.

Data Size Limit

In most cases, each query also has a limit on the amount of data you can query in a single request. If this amount is exceeded, you will be met with the error message: "The data you are requesting exceeds the allowed data size..." To correct this issue, you can either reduce the date range supplied to the query, or reduce the amount of devices/device ids supplied to the query (where applicable).

What is the latest API Version?

The latest Rhino Fleet Tracking API version is v2.0.
Effective date: 12-18-2020

v2.0 Release Notes

Events Report

• argument begin is now startDatetime
• argument end is now endDatetime
• The above arguments are now strictly formatted strings and only except the datetime format: "YYYY-MM-DD HH:mm:ss"
• Fields: Previously, you would need to query rows as well as the fields it contained. Now, you can simply query the content you need.

OLD (V1.0 Deprecated):

  query eventsReport($begin: String!, $end: String!, $eventTypes: [EventEnum]!, $deviceIds: [Int]){
    eventsReport(begin: $begin, end: $end, eventTypes: $eventTypes, deviceIds: $deviceIds){
      rows{
        deviceId
        alias
        lat
        lng
        ...
      }
    }
  }

NEW:

  query eventsReport($startDatetime: String!, $endDatetime: String!, $eventTypes: [EventEnum]!, $deviceIds: [Int]){
    eventsReport(startDatetime: $startDatetime, endDatetime: $endDatetime, eventTypes: $eventTypes, deviceIds: $deviceIds){
      deviceId
      alias
      lat
      lng
      ...
    }
  }

Trips Report

• argument begin is now startDatetime
• argument end is now endDatetime
• The above arguments are now strictly formatted strings and only except the datetime format: "YYYY-MM-DD HH:mm:ss"
• Fields: Previously, you would need to query rows as well as the fields it contained. Now, you can simply query the content you need.

OLD (V1.0 Deprecated):

  query tripsReport($begin: String!, $end: String!, $deviceIds: [Int]){
    tripsReport(begin: $begin, end: $end, deviceIds: $deviceIds){
      rows{
        id
        alias
        trips {
          id
          tripOrder
          duration
          ...
        }
      }
    }
  }

NEW:

  query tripsReport($startDatetime: String!, $endDatetime: String!, $deviceIds: [Int]){
    tripsReport(startDatetime: $startDatetime, endDatetime: $endDatetime, deviceIds: $deviceIds){
      id
      alias
      trips{
        id
        tripOrder
        duration
        ...
      }
    }
  }

Documentation

Much of the documentation has been updated in hopes that we can continue to make this API as easily accessible as possible. We've provided quick links in the side menu as well as within the documentation to help you jump to the resources you need more quickly. We've also added more descriptive information on the various queries as well as some of our schema types to help you better understand the environment we provide.

Lastly, we added documentation on how we limit the API queries. For details on this, visit API Limiting.

Below is a list of some useful links as well as short descriptions as to what you can find from visiting them.

Resources/Reference

• https://graphql.org/code/ - Links to GraphQL documentation in various programming languages
• https://www.apollographql.com/docs/react/ - Apollo Client demonstrated in React.js
• https://gist.github.com/dunglas/05d901cb7560d2667d999875322e690a - A minimalist GraphQL client for PHP (example)