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
Authorization
string
Bearer <token>
Content-Type
string
application/json
Request Body
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