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.
Our default 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.
For other environments, please ask your sales representative or support@sentiance.com for the custom endpoint linked to your environment.
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"}}]}}}
While you can always discover and play around with Graphql in our Data Explorers, you might wish to programatically introspect our Schema for your own tools to parse. You can do so by firing off an Introspection Query.
QUERYquery IntrospectionQuery {__schema {queryType {name}mutationType {name}subscriptionType {name}types {...FullType}directives {namedescriptionlocationsargs {...InputValue}}}}​fragment FullType on __Type {kindnamedescriptionfields(includeDeprecated: true) {namedescriptionargs {...InputValue}type {...TypeRef}isDeprecateddeprecationReason}inputFields {...InputValue}interfaces {...TypeRef}enumValues(includeDeprecated: true) {namedescriptionisDeprecateddeprecationReason}possibleTypes {...TypeRef}}​fragment InputValue on __InputValue {namedescriptiontype {...TypeRef}defaultValue}​fragment TypeRef on __Type {kindnameofType {kindnameofType {kindnameofType {kindnameofType {kindnameofType {kindnameofType {kindnameofType {kindname}}}}}}}}​
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.
QUERYquery {moment_definitions {idtypecategorydisplay_name}}​RESPONSE{"data": {"moment_definitions": [{"id": "working_at_work","type": "MomentDefinition","category": "activity","display_name": "Working at work"},{...}]}}
QUERYquery {segment_definitions(status: ALPHA) {idtypecategorydisplay_name}}​RESPONSE{"data": {"segment_definitions": [{"id": "mobility.passenger","type": "SegmentDefinition","category": "passenger","display_name": "Passenger"},{...}]}}
QUERYquery($user_id: String!, $from:String, $to: String) {user(id: $user_id) {event_history(from: $from, to:$to) {typestartendanalysis_type... on Stationary {latitudelongitudelocation {significance}}... on Transport {modedistance}}}}​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},{...}]}}}
QUERYquery($user_id: String!, $from:String, $to: String) {user(id: $user_id) {idmoment_history(from: $from, to:$to) {startendanalysis_typemoment_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"},{...}]}}}
​