GraphQL

Our API primarily speaks GraphQL (GQL, for short). While explaining how GraphQL works is beyond the scope of this guide, there are excellent resources available on the interwebs.
Here we will introduce the basic request response structure of the Sentiance GraphQL API.
Endpoint and Authorization
Our GraphQL endpoint lives at POST https://api.sentiance.com/v2/gql and accepts the same bearer token based authorization as our REST endpoints.​
We adhere to the GraphQL specification but do not support multiple operation types.
Our US and Australian customers can go to https://api.d4.sentiance.com/v2/gql and https://api.e6.sentiance.com/v2/gql respectively.
post
GQL Request
https://api.sentiance.com/v2/gql
Request
Response
Headers
Authorization
required
string
Bearer <token>
Content-Type
required
string
application/json
Body Parameters
query
required
string
The GraphQL query.
variables
required
object
A flat JSON object describing the variables to substitute in the query.
200: OK
This would depend on the query made. An example of query/response is presented here.
REQUEST 
{
  "query": "query($user_id: String!) {\n  user(id: $user_id) {\n    id\n    event_history(from: \"2019-04-01\", to:\"2019-04-02\") {\n      type\n      start\n      end\n      analysis_type\n      ... on Stationary {\n        latitude\n        longitude\n        location {\n          significance\n        }\n      }\n      ... on Transport {\n        mode\n        distance\n      }\n    }\n  }\n}",
  "variables": {
    "user_id": "5a93deb3d8e7d90600001e6f"
  }
}
​
RESPONSE
{
  "data": {
    "user": {
      "id": "5a93deb3d8e7d90600001e6f",
      "event_history": [
        {
          "type": "Stationary",
          "start": "2019-02-05T09:25:01.000+01:00",
          "end": null,
          "analysis_type": "indepth",
          "latitude": 51.19654,
          "longitude": 4.40794,
          "location": {
            "significance": "new"
          }
        }
      ]
    }
  }
}
Examples
Some examples of various GQL queries with example response are presented here. With GraphQL you can fetch as much or as little as you wish. 
Moment Definitions
QUERY
query {
  moment_definitions {
    id
    type
    category
    display_name
  } 
}
​
RESPONSE
{
  "data": {
    "moment_definitions": [
      {
        "id": "working_at_work",
        "type": "MomentDefinition",
        "category": "activity",
        "display_name": "Working at work"
      },
      {...}
    ]
  }
}
Alpha Segments
QUERY
query {
  segment_definitions(status: ALPHA) {
    id
    type
    category
    display_name
  } 
}
​
RESPONSE
{
  "data": {
    "segment_definitions": [
      {
        "id": "mobility.passenger",
        "type": "SegmentDefinition",
        "category": "passenger",
        "display_name": "Passenger"
      },
      {...}
    ]
  }
}
User Timeline Query
QUERY
query($user_id: String!, $from:String, $to: String) {
  user(id: $user_id) {
    event_history(from: $from, to:$to) {
      type
      start
      end
      analysis_type
      ... on Stationary {
        latitude
        longitude
        location {
          significance
        }
      }
      ... on Transport {
        mode
        distance
      }
    }
  }
}
​
VARIABLES
{ 
  "user_id": "583e08a1cd99250700000002",
  "from": "2019-03-22",
  "to": "2019-03-23"
}
​
RESPONSE
{
  "data": {
    "user": {
      "event_history": [
        {
          "type": "Stationary",
          "start": "2019-03-23T19:51:49.000+01:00",
          "end": "2019-03-25T08:30:21.000+01:00",
          "analysis_type": "indepth",
          "latitude": 51.78561,
          "longitude": 42.49694,
          "location": {
            "significance": "home"
          }
        },
        {
          "type": "Transport",
          "start": "2019-03-23T19:49:49.000+01:00",
          "end": "2019-03-23T19:51:49.000+01:00",
          "analysis_type": "indepth",
          "mode": "walking",
          "distance": null
        },
        {...}
      ]
    }
  }
}
User Moment History
QUERY
query($user_id: String!, $from:String, $to: String) {
  user(id: $user_id) {
    id
    moment_history(from: $from, to:$to) {
      start
      end
      analysis_type
      moment_definition_id
    }
  }
}
​
VARIABLES
{ 
  "user_id": "583e08a1cd99250700000002",
  "from": "2019-03-22",
  "to": "2019-03-23"
}
​
RESPONSE
{
  "data": {
    "user": {
      "id": "583e08a1cd99250700000002",
      "moment_history": [
        {
          "start": "2019-03-23T19:51:49.000+01:00",
          "end": "2019-03-25T08:30:21.000+01:00",
          "analysis_type": "processed",
          "moment_definition_id": "home"
        },
        {
          "start": "2019-03-23T19:22:40.000+01:00",
          "end": "2019-03-23T19:49:49.000+01:00",
          "analysis_type": "processed",
          "moment_definition_id": "shopping_routine"
        },
        {...}
      ]
    }
  }
}
​
Backend - Previous
Authentication and Authorization
Next - Backend
REST API Reference
Last updated last month
GraphQL

Endpoint and Authorization

postGQL Request

Examples

Moment Definitions

Alpha Segments

User Timeline Query

User Moment History

post
GQL Request
