Use REST API for getting Events

GpsGate REST API is a core functionality which is distributed with the Updates.v5 plugin. Installing the plugin updates your application to the latest version of GpsGate REST API. To control access to API resources, _APIRead and _APIReadWrite privileges are used. _APIRead is for granting read-only access and _APIReadWrite is for granting read/write access. Most services also offer resource-based privileges which can be used for filtering access to that specific resource. By default, applications/users have no access to API resources.

Activate API privileges

To activate API privileges for an application, follow these steps:

  1. Login to Site Admin
  2. Navigate to Applications and select the application in which you want to grant access to RESTful API
  3. Under API enable _APIRead and _APIReadWrite 
  4. Click on Save


Enable API in your application roles

After enabling the privileges for an application, follow these steps to allow API access to the Roles you choose:

  1. Log in to the application
  2. Select Roles from Admin menu
  3. Create a new role for API users or edit an existing role
  4. Under the Users section, select the users you want to add to this role
  5. Under Privileges section, enable _APIRead privilege for read-only access and _APIReadWrite privilege for full access.
  6. Press Save

Accessing the API

In order to use GpsGate API, you need an HTTP client. There are many applications available on the Internet that can be used for this purpose. You can also develop your own HTTP client using your preferred programming language.

Another alternative is to use our web-based HTTP client for manual testing that is distributed with Updates.v5 plugin. You can reach this client by typing the following URL: http://host_name/comGpsGate/api/v.1/test (replace host_name with your actual server IP address or hostname).

In this tutorial, we use yet another client called Postman to show HTTP headers and other details.


The first step to use GpsGate REST API is to log in. To log in into GpsGate REST API you need to send your username and password to the token resource. The response of your request will contain an API Token which you can use to authenticate yourself in the following requests. For an example of a login request and how to use the response, please read the token section.

Resources and Actions

All available resources are documented in a page hosted by your GpsGate installation:
http://host_name/comGpsGate/api/v.1/test (replace host_name with your actual server IP address or hostname).

An HTTP Authorization header with an API Token as value should be sent along with requests to the resources that require authentication. Below is an example of an HTTP request that is created by Postman. In the next section, we explain how to acquire your API token.

Tokens (/applications/{applicationid}/tokens):
As mentioned before, the Token resource is for authentication purposes. This resource is used to log in and get an API token back. The token should be sent in all communications with other resources. To get the API token for a user, an HTTP POST request should be sent to the Token resource. In the post body, username and password are specified in JSON format, and the response body contains a token key with an actual API Token as value. The token should be used in an HTTP Authorization header while communicating with other resources. Depending on the client that is used, there are different ways to send HTTP headers.

The following picture shows how to use Postman to send a login request to the Token resource and how the response looks.

For more information about how to send the token in an authorization header using our test client, please read the Testing section.

Please note that the full URI of the token resource is “http://{hostname}:{port}/comGpsGate/api/v.1/applications/{applicationid}/tokens” where your GpsGate Server is installed on “{hostname}” and it listens to port number “{port}” (the default port is 80) and “{applicationid}” is Id of the application you are trying to login to.

An example of the URI is http://localhost:80/comGpsGate/api/v.1/applications/4/tokens where GpsGate Server is installed on the local computer and listens to the default port and the application we try to login to is application number 4.

Users (/applications/{applicationid}/users):
The HTTP GET request on this resource returns a list of users in the application.

Event Rules (/applications/{applicationid}/eventrules):
HTTP GET can be used to get a list of event rules in an application.

Events (/applications/{applicationid}/events):
HTTP GET can be used to get a list of events for a combination of a specific application, event rule, user, and date. The OpenEvents parameter can be passed to specify if only open events should be returned.


In order to test the API, you can develop your own client or use one of the many third-party tools available on the Internet to generate the client code for your preferred programming language from our standard documentation. GpsGate API documentation is based on the OpenAPI Specification. You can download the GpsGate RESTful API specification here: http://host_name/comGpsGate/api/v.1/swagger.json (replace host_name with your actual server IP address or hostname). For quickly accessing the API and manual testing, you can use our web-based client available in the documentation page. You can reach the page using this link: http://host_name/comGpsGate/api/v.1/test (replace host_name with your actual server IP address or hostname). The client has been generated using Swagger tools.

Here we provide an example of how to generate an API token for a user and use it for getting a list of tags using our web-based client. First, you visit the documentation page hosted by your GpsGate Server installation. Then, a request should be sent to the Token resource as shown in the following picture.

The response from the server contains the API Token (in this case “9Zg4HihvlYr6Y5Py0vdH91O8O6my80Ll30RPUf3S9kpz%2brvLrwtiEPN8eQT%2f5vGe”)

For ease of use, there is an Authorize button on top of the page which can be used to set the API token. After pasting the API token and pressing the Authorize button, the token will be sent in an Authorization header for all the other requests. This functionality can be used to bypass adding an Authorization header for each request during manual testing. The following pictures show how to set the API token.

Please note that the lock icon is locked and the Token will be sent along with all requests. As an example, we use the Tags resource (as shown in the following picture) to fetch the list of tags.

Performance and Pagination

To improve the performance and have better scalability, there is a limit of 1000 records in the response of an HTTP GET request. This number can be decreased by sending PageSize parameters in the query string of your request, however, it cannot exceed 1000. If there are more records than the number specified in the PageSize parameter (or 1000 by default), a link to the next page is sent back along with the response in x-pagination header. Here is an example of x-pagination header for a request where the specified PageSize was 100.