API Documentation

Base HTTP URL

The base URL is https://api.geospark.co/api/v1/, with entity URLs like https://api.geospark.co/api/v1/apps/. Every URL ends with a forward-slash /.

Contents

  1. Authentication
  2. HTTP request headers
    • Authorization
    • Content type
  3. API error codes

1. Authentication

Use your secret key to authenticate HTTP API calls. Your secret key is available on the account settings page, and looks like ed158425a218971ae1fa6a683776ff25f8e49daa.

Secret key

The secret key is authorized for all API calls - to create, edit, list, retrieve and delete data. It looks like ed158425a218971ae1fa6a683776ff25f8e49daa.

The secret key is used on the server-side, for backend-to-backend communication. As the name suggests, you should never share your secret key., which includes putting it into any public code source.

2. HTTP request headers

Authorization

The API follows HTTP basic auth to authenticate API calls with a token. Every API call needs to have the Authorization key sent in the request header with the token, as shown below.


  Authorization: token ed158425a218971ae1fa6a683776ff25f8e49daa


Content type

While sending POST requests with a JSON body, remember to add the Content-Type header to define input format.


  Content-Type: application/json


3. API error codes

The GeoSpark REST API uses the following error codes. For each error response, the response content contains information on what is wrong.

Error code Meaning
301 Redirect to correct API url
400 Missing or invalid parameters in API call
401 Missing or invalid API token
402 You don't have permission to access the resource. Please check your billing setup
403 You don't have permission to access the resource, verify your token
404 The resource does not exist, check the URL
405 You tried to access a resource with an invalid HTTP method
5xx There was an error on the server and we have been notified

API Entities

The GeoSpark API has the following entities.

Entity Description
Application Represents the application
User Represents the person who is being tracked

API calls

Base Url: https://api.geospark.co/api/v1/

API call Method URL Description
Retrieve all applications GET apps/ Get list of all applications created.
Retrieve all users GET users/ Get list of all users associated with the given application
Retrieve user data GET users/data/ Retrieve user data aggregated between given date range.

Retrieve all applications

Get list of all applications created.

HTTP Request

GET https://api.geospark.co/api/v1/apps/

Returns

Returns a list of all applications created.


  curl -H "Authorization: token YOUR_API_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -X GET \

     https://api.geospark.co/api/v1/apps/


Retrieve all users

Get list of all users associated with given application.

HTTP Request

GET https://api.geospark.co/api/v1/users/

Returns

Returns a list of all users created.

Parameters

Parameter Required Description
app_id True Application id to get list of users associated with the application
start_date False Retrieve users list starting from this timestamp. Default is since account was created. (Format: YYYY-MM-DD)
end_date False Retrieve users list starting to this timestamp. Default is current date. (Format: YYYY-MM-DD)
page False Retrieve users list of the given page. Default is 1.

  curl -H "Authorization: token YOUR_API_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -X GET \

     https://api.geospark.co/api/v1/users/?app_id=APPLICATION_ID&start_date=START_DATE&end_date=END_DATE&page=PAGE


Retrieve user data

Get user data aggregated between given date range

HTTP Request

GET https://api.geospark.co/api/v1/users/data/

Returns

Returns user data aggregated between given date range.

Parameters

Parameter Required Description
user_id True User id to get list of data associated with the user.
start_date False Retrieve user data starting from this timestamp. Default is current date. (Format: YYYY-MM-DD)
page False Retrieve user data of the given page. Default is 1.

  curl -H "Authorization: token YOUR_API_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -X GET \

     https://api.geospark.co/api/v1/users/data/?user_id=USER_ID&start_date=START_DATE&page=PAGE