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 default GraphQL endpoint lives at POST https://api.sentiance.com/v4/gql and accepts the same bearer token based authorization.

We adhere to the GraphQL specification but do not support multiple operation types.

Since it is possible for a single HTTP request to encompass multiple GraphQL queries with some of them succeeding and some of them failing, the endpoint always returns a 200 OK, unless something severe enough happens on the server-side to guarantee failure of the entire response (such as a 500 status code). After checking for the 200 status code, please also check the body of the response for data and error properties.

For other environments, please ask your sales representative or support@sentiance.com for the custom endpoint linked to your environment.

GQL Request

POST https://api.sentiance.com/v4/gql

Headers

Name
Type
Description

Authorization

string

Bearer <token>

Content-Type

string

application/json

Request Body

Name
Type
Description

query

string

The GraphQL query.

variables

object

A flat JSON object describing the variables to substitute in the query.

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"
          }
        }
      ]
    }
  }
}

Introspection

While you can always discover and play around with GraphQL in our Data Explorer, you might wish to programatically introspect our Schema for your own tools to parse. You can do so by firing off an Introspection Query.

÷QUERY
query IntrospectionQuery {
  __schema {
    queryType {
      name
    }
    mutationType {
      name
    }
    subscriptionType {
      name
    }
    types {
      ...FullType
    }
    directives {
      name
      description
      locations
      args {
        ...InputValue
      }
    }
  }
}

fragment FullType on __Type {
  kind
  name
  description
  fields(includeDeprecated: true) {
    name
    description
    args {
      ...InputValue
    }
    type {
      ...TypeRef
    }
    isDeprecated
    deprecationReason
  }
  inputFields {
    ...InputValue
  }
  interfaces {
    ...TypeRef
  }
  enumValues(includeDeprecated: true) {
    name
    description
    isDeprecated
    deprecationReason
  }
  possibleTypes {
    ...TypeRef
  }
}

fragment InputValue on __InputValue {
  name
  description
  type {
    ...TypeRef
  }
  defaultValue
}

fragment TypeRef on __Type {
  kind
  name
  ofType {
    kind
    name
    ofType {
      kind
      name
      ofType {
        kind
        name
        ofType {
          kind
          name
          ofType {
            kind
            name
            ofType {
              kind
              name
              ofType {
                kind
                name
              }
            }
          }
        }
      }
    }
  }
}

GraphQL Specification

The GraphQL Specification can be found in the file below. Additional details for fields and structures present in GraphQL are found in our Data Reference page.

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.

Transport details

QUERY
query($user_id: String, $from: String, $to: String) {
  user(user_id: $user_id) {
    user_id
    transports(from: $from, to: $to) {
      transport_id
      mode
      start_at
      end_at
      trajectory {
        start_location {
          country
          region
          city
          district
          street
        }
        end_location {
          country
          region
          city
          district
          street
        }
      }
    }
  }
}

VARIABLES
{
  "user_id" : "<user_id>",
  "from" : "2022-10-05",
  "to" : "2022-10-05"
}

RESPONSE
{
  "data": {
    "user": {
      "external_id": null,
      "transports": [
        {
          "end_at": "2022-10-04T10:46:00.000+02:00",
          "mode": "WALKING",
          "start_at": "2022-10-04T10:44:31.000+02:00",
          "trajectory": {
            "end_location": {
              "city": "Antwerpen",
              "country": "België / Belgique / Belgien",
              "district": "Antwerpen",
              "region": "Vlaanderen",
              "street": "Sentiancestraat"
            },
            "start_location": {
              "city": "Antwerpen",
              "country": "België / Belgique / Belgien",
              "district": "Antwerpen",
              "region": "Vlaanderen",
              "street": "Gerardlaan"
            }
          },
          "transport_id": "<transport_id>"
        },
        {
          "end_at": "2022-10-04T10:44:00.000+02:00",
          "mode": "TRAM",
          "start_at": "2022-10-04T10:46:00.000+02:00",
          "trajectory": {
            "end_location": {
              "city": "Antwerpen",
              "country": "België / Belgique / Belgien",
              "district": "Antwerpen",
              "region": "Vlaanderen",
              "street": "Gerardlaan"
            },
            "start_location": {
              "city": "Antwerpen",
              "country": "België / Belgique / Belgien",
              "district": "Antwerpen",
              "region": "Vlaanderen",
              "street": "Sentiancestraat"
            }
          },
          "transport_id": "<transport_id>"
        },
        ......
      ],
      "user_id": "<user_id>"
    }
  }
}

Trajectory

QUERY
# Write your query or mutation here
query($user_id: String, $from: String, $to: String) {
  user(user_id: $user_id) {
    user_id
    transports(from: $from, to: $to) {
      transport_id
      trajectory {
        distance
        polyline
      }
    }
  }
}

VARIABLES
{
  "user_id" : "<user_id>",
  "from" : "2022-10-05",
  "to" : "2022-10-05"
}

RESPONSE
{
    "data": {
      "user": {
        "transports": [
          {
            "trajectory": {
              "distance": 163.25,
              "polyline": "f143f43413fc43c43c31c34c3"
            },
            "transport_id": "<transport_id>"
          },
          {
            "trajectory": {
              "distance": 4163.2,
              "polyline": "iyqwHal~YhAOf@Ej@E34f243f34f3FA~Bs@BADARIVKBAlDgC^WTQFEHILT@BzA~BdAbBr@hAJPzBpDHLBF@DJh@?P?LDRDVFNHPLPFHJFJFHBh@JHBJLFFDFxBjDFJ@@?@JNBDhBzCZf@JPHLpAtBrD`GLPHNlAdB@B??v@lApB|CHLJNJN@BOHCBOJuFdDoAr@qAv@EBQJBL@HDRPK~BsAlC_BzCaBLIDCPId@MDALFD@nCfA|ErB~ClA|@\\PHPFD@@@JAFCFEDGMSEGKOIQIWKa@Gc@Gk@Ec@Eg@EcAASEe@Is@GUESISGQMYIOOWOSEIIGGGECICOGSCCA]AEAE?AAECECs@n@eDnCc@`@YVWR_@ZEBA@SNBJ@@?@@D?B@B@D?@@BBJLFD@nCfA|ErB~ClA|@\\PHPFD@@@JAFCFEDGMSEGKOIQIWKa@Gc@Gk@Ec@Eg@EcAASEe@Is@GUESISGQMYIOOWOSEIIGGGECICOGSCCA]AEAE?AAECECs@n@eDnCc@`@YVGW[oA??"
            },
            "transport_id": "<transport_id>"
          }
        ],
        "user_id": "<user_id>"
      }
    }
  }

Significant driving events

QUERY
query($user_id: String, $from: String, $to: String) {
  user(user_id: $user_id) {
    user_id
    transports(from: $from, to: $to) {
      transport_id
      driving_events {
        accelerating {
          duration
          start_at
          end_at
          type
          category
        }
        braking {
          duration
          start_at
          end_at
          type
          category
        }
        calls {
          duration
          start_at
          end_at
          type
          category
        }
        mounted {
          duration
          start_at
          end_at
          type
          category
        }
        phone_handling {
          duration
          start_at
          end_at
          type
          category
        }
        screens {
          duration
          start_at
          end_at
          type
          category
        }
        accelerating {
          duration
          start_at
          end_at
          type
          category
        }
        turning {
          duration
          start_at
          end_at
          type
          category
        }
      }
    }
  }
}

VARIABLES
{
  "user_id" : "<user_id>",
  "from" : "2022-10-05",
  "to" : "2022-10-05"
}

RESPONSE
{
  "data": {
    "user": {
      "transports": [
        {
          "driving_events": {
            "accelerating": [
              {
                "category": "accelerating",
                "duration": 11.2,
                "end_at": "2022-10-05T09:09:18.000+02:00",
                "start_at": "2022-10-05T09:09:06.800+02:00",
                "type": "accelerate"
              },
              {
                "category": "accelerating",
                "duration": 4.2,
                "end_at": "2022-10-05T09:10:04.100+02:00",
                "start_at": "2022-10-05T09:09:59.900+02:00",
                "type": "accelerate"
              },
              ......
            ],
            "braking": [
              {
                "category": "braking",
                "duration": 7.6,
                "end_at": "2022-10-05T09:08:54.800+02:00",
                "start_at": "2022-10-05T09:08:47.200+02:00",
                "type": "brake"
              }
            ],
            "calls": [],
            "mounted": [
              {
                "category": "mounted",
                "duration": 30,
                "end_at": "2022-10-05T09:10:16.200+02:00",
                "start_at": "2022-10-05T09:09:46.200+02:00",
                "type": "mounted"
              }
            ],
            "phone_handling": [
              {
                "category": "phone_handling",
                "duration": 12,
                "end_at": "2022-10-05T09:05:38.200+02:00",
                "start_at": "2022-10-05T09:05:26.200+02:00",
                "type": "phone_handling"
              },
              {
                "category": "phone_handling",
                "duration": 22,
                "end_at": "2022-10-05T09:06:02.200+02:00",
                "start_at": "2022-10-05T09:05:40.200+02:00",
                "type": "phone_handling"
              }
            ],
            "screens": [
              {
                "category": "screen_events",
                "duration": 90.3,
                "end_at": "2022-10-05T09:06:52.300+02:00",
                "start_at": "2022-10-05T09:05:22.000+02:00",
                "type": "screen_events"
              },
              {
                "category": "screen_events",
                "duration": 42.1,
                "end_at": "2022-10-05T09:08:03.300+02:00",
                "start_at": "2022-10-05T09:07:21.200+02:00",
                "type": "screen_events"
              }
            ],
            "turning": [
              {
                "category": "turning",
                "duration": 5.6,
                "end_at": "2022-10-05T09:09:22.400+02:00",
                "start_at": "2022-10-05T09:09:16.800+02:00",
                "type": "right_turn"
              },
              {
                "category": "turning",
                "duration": 1.8,
                "end_at": "2022-10-05T09:09:32.100+02:00",
                "start_at": "2022-10-05T09:09:30.300+02:00",
                "type": "left_turn"
              },
              .......
            ]
          },
          "transport_id": "<transport_id>"
        }
      ],
      "user_id": "<user_id>"
    }
  }
}

Driving scores

QUERY
query($user_id: String, $from: String, $to: String) {
  user(user_id: $user_id) {
    user_id
    transports(from: $from, to: $to) {
      transport_id
      scores {
        safety {
          primary {
            smooth
            attention
            legal
            overall
          }
        }
      }
    }
  }
}

VARIABLES
{
  "user_id" : "<user_id>",
  "from" : "2022-10-05",
  "to" : "2022-10-05"
}

RESPONSE
{
  "data": {
    "user": {
      "transports": [
        {
          "scores": {
            "safety": {
              "primary": {
                "attention": 0.42,
                "legal": 0.95,
                "overall": 0.77,
                "smooth": 0.95
              }
            }
          },
          "transport_id": "<transport_id>"
        },
        {
          "scores": {
            "safety": {
              "primary": {
                "attention": -1,
                "legal": -1,
                "overall": -1,
                "smooth": -1
              }
            }
          },
          "transport_id": "<transport_id>"
        },
        .......
      ],
      "user_id": "<user_id>"
    }
  }
}

Aggregated Score

query($user_id: String, $date: String) {
  user(user_id: $user_id) {
    user_id
    scores (by: "DAY", date: $date) {
      driving {
        safety {
          primary {
            smooth
            attention
            legal
            overall
          }
          secondary {
            focus
            mounted
            anticipation
            harsh_braking
            harsh_turning
            harsh_acceleration
          }
        }
      }
    }
  }
}

VARIABLES
{
  "user_id" : "<user_id>"
  "date" : "2022-10-05"
}

RESPONSE
{
  "data": {
    "user": {
      "scores": {
        "driving": {
          "safety": {
            "primary": {
              "attention": 0.77,
              "legal": 1,
              "overall": 0.83,
              "smooth": 0.71
            },
            "secondary": {
              "anticipation": 0.86,
              "focus": 1,
              "harsh_acceleration": 0.95,
              "harsh_braking": 1,
              "harsh_turning": 1,
              "mounted": 0
            }
          }
        }
      },
      "user_id": "<user_id>"
    }
  }
}

Last updated