Intel® Cloud Services Platform beta Context Services REST API Reference

Context Services REST API Information

Interface Basics

API Call Groups

Resources APIs

Item APIs

Watch APIs

Behavior Model APIs

Response Codes and Error Handling

Legal Information

Related Information

Context Services APIs enable you to build context-aware applications and services that are aware of, responsive to, and personalized to a user's situation while empowering users with ultimate control over their privacy.

For an overview of Context Services, including background on the APIs, see Context Services Developer Guide.

For a sample walkthrough that steps you through Context Services calls, see the Context Services REST API Interactive Demo.

Context Services REST API Information

All applications begin by authorizing with an agent of the Intel Cloud Services Platform to obtain an access token, regardless of which services the application uses. Apps must include this access token in all subsequent calls during the session.

For more information on this process, see Intel® Cloud Services Platform beta REST Authorization Overview.

Interface Basics

The following list provides basic information to help implement the API calls:

  • Each API call is placed to a unique URL responsible for providing the requested resources.
  • Requests that have bodies as well as responses to API calls are returned in JSON (JavaScript* Object Notation).
  • Sessions are automatically terminated after an extended period of inactivity.
  • Multiple concurrent sessions for an application are supported. Each session will use a unique access token obtained when that session logs in. The application is responsible for keeping track of the access tokens and their proper association with the sessions.
  • For all APIs where the operation URL includes the substitution value {user_id}, the URL can use the value "me" to indicate that the user is extracted from the access token submitted with the API.
  • For all APIs where the operation URL includes the substitution value {app_instance_id}, the URL can use the value "this" to indicate that the application is extracted from the authorization token submitted with the API.
  • For query options, you can specify an array as a parameter by providing multiple (key=value) pairs with the same key.
  • Getting started information about registering your apps, subscribing to services, authenticating, testing the services and publishing your apps is available here.

API Call Groups

The following table lists each API by its call group and summarizes the function of the call. The APIs are described in details in the sections that follow this table.

Call Headers

Context Services calls all require this header input:

Authorization: Bearer {access_token}

In JSON samples, headers use the term "token"and refers to the token returned by the initial call to the Intel® Identity Services.

Orderly JSON

Orderly JSON is a format for describing JSON that is intended to be easy to read. For more information, see Orderly. This site can convert your Orderly to JSON Schema format (or vice versa) if you prefer.

Context Services REST API Call Groups

Data Types
Call Description
Get Supported Resource Types Obtains resource type information, including schemas, descriptions, and documentation.
Items
Call Description
Query Stored Items Querying /items returns results filtered by the caller's access permission and then by specified filter parameters.
Store New Items Uploads data to the Context Services by posting a set of ContextItem structures to the /items collection.
Delete Stored Items Removes all context items that match the caller's access permission and query parameters.
Get Item (ID) Gets the context information about a specific item, such as the item's context type, owner, ID, and client and server created times.
Delete Item (ID) Deletes a specific item or items using the item ID.
Watches
Call Description
Get Watches Returns the set of ContextWatch objects specified by the calling application.
Create Watch Creates a watch associated with the calling application.
Get Watch (ID) Uses a watch ID to get new context information for a specific watch.
Delete Watch (ID) Deletes watch object associated with the calling application.
Get New Items That Match Watches Gets the new context items created since the last time a GET of /watches/newitems was performed.
Behavior Model
Call Description
List Possible Next Destinations Suggests the next location that the user will go by analyzing context that was gathered for that user.
Get Point of Interest Weights from Behavior Model Queries the model for point of interest attributes.
Get Place Gets the user's location.
Predict Activity Predicts what the user is doing based on the time of day.

Resources APIs

The API calls in this section are for two categories of resources: context type resources and analysis model resources. The context type resources are:

Context Resource Type URN
Location search history urn:x-intel:context:type:search
Travel route history urn:x-intel:context:type:location:route
Location visits
 
Preferred:
urn:x-intel:context:type:location:checkin:v1

Or:
urn:x-intel:context:type:location:checkin
Current location urn:x-intel:context:type:location:current
Likes and Ratings urn:x-intel:context:type:rating
Application specific data urn:x-intel:context:type:developer-private
Behavioral Model urn:x-intel:context:behaviormodel

A GET call to /typescatalog returns not just a list of each available resource, but also the schema for each resource, and descriptions of the fields. Because new resources are likely to be added to the services, calling typescatalog is the best way to get the most current resource information.

The following is the Orderly JSON format for the typescatalog object.

object { 
    string identifier; 
    string category ["context-type", "model"]; 
    array [string;] accessTypes
    string lang;
    string shortname;
    string documentation;
    object valueSchema; 
};

This table describes the fields of the typescatalog object.

Field Definition
identifier Resource type identifier.
category The category of the resource. Can be either "context-type" or "model." A "context-type" resource represents data entries that can be posted and manipulated in the /items API. A "model" resource is accessed via the /users/{userid}/models family of APIs. (see Behavior Model APIs below.)
accessTypes Describe the operations you can perform on the context type. Can be create, read, update, or delete.
lang The language that the types are in.
shortname Friendly name for the resource type.
documentation The description of the resource type.
valueSchema The JSON schema document for the type. For "context-type" resources, the schema describes the "value" content of a context item with this type. For the "model" resource, the schema describes the data returned from an evaluation of the model.

Context Resource Type IDs

Context resource type IDs are used to identify the type of each context item in the /items API, and to represent context data or an analysis model as a resource throughout the service. For example, the resource URI in the authorization APIs.

Context data type IDs are usually defined with a URI in the following format:

urn:x-intel:context:type:{category}:{detail}:v{revision-number}

Context analysis model IDs are usually defined with a URI in the following format:

urn:x-intel:context:model:{model-name}:{model-capability}:v{revision-number}

For example:

urn:x-intel:context:type:location:route

Get Supported Resource Types

Obtains the list of context resource types supported by Context Services, as well as schemas, descriptions, and documentation. The list is read-only to all clients.

URL Structures

https://api.intel.com:8081/context/v1/typescatalog
Authorization: Bearer <token>

Method: GET

For types associated with a set of specific identifiers:

https://api.intel.com:8081/context/v1/typescatalog?ids={id}
Authorization: Bearer {access_token}

Method: GET

For types that have an identifier beginning with a specific string:

https://api.intel.com:8081/context/v1/typescatalog?identifierBeginsWith={string}
Authorization: Bearer {access_token}

Method: GET

Input Parameters

Input Required Input Type Description
None no   No query string causes the services to return all of the type values present in the service.
ids no string One or more specific identifiers that, when included, return associated resource types.
identifierBeginsWith no string Beginning of identifier, which, when included, gets the types from the services with an identifier starting with the specified string.

Example Usage

GET https://api.intel.com:8081/context/v1/typescatalog
Authorization: Bearer {access_token}

For types associated with a set of specific identifiers:

GET https://api.intel.com:8081/context/v1/typescatalog?ids=urn:x-intel:context:location:current&ids=urn:x-intel:context:type:location:route
Authorization: Bearer {access_token}

For types that have an identifier beginning with a specific string:

GET https://api.intel.com:8081/context/v1/typescatalog?identifierBeginsWith=urn:x-intel:context:location
Authorization: Bearer {access_token}

JSON Request

None

Response Codes

HTTP Code Message Description
200 OK The request was successful. An array of type information was returned.
404 Not Found The specific types were not found.
500 Internal Error Servers are not working as expected. The request might be valid but needs to be retried later.

JSON Response

The following is an example of one context type.

Note: In many context types, an additionalProperties flag is set to "false". This indicates that no other properties can be included in the schema for the property that's being described.

{
    "data": {
        "items": [
            {
                "identifier": "urn:x-intel:context:type:location:current",
                "category": "context-type",
                "lang": "en-US",
                "shortName": "Current location",
                "documentation": "Current location as reported by...",
                "valueSchema": {
                     "additionalProperties": false,
                     "properties": {
                         "name": {
                             "required": false,
                             "type": "string",
                             "description": "name"
                         },
                         "source_domain": {
                             "required": false,
                             "type": "string",
                             "description": "Target service for the search
                                  E.g: google, tripIt"
                         },
                         "value": {
                             "required": true,
                             "type": "string",
                             "description": "Search used to perform the search"
                         },
                         "datetime": {
                             "required": true,
                             "type": "datetime",
                             "description": "Date and time when the search was 
                                  performed in local format including timezone"
                         },
                         "location": {
                             "additionalProperties": false,
                             "required": true,
                             "properties": {
                                 "lat": {
                                     "required": true,
                                     "type": "number",
                                     "description": "Latitude where the 
                                        search was performed"
                                 },
                                 "lon": {
                                     "required": true,
                                     "type": "number",
                                     "description": "Longitude where the 
                                         search was performed"
                                 }
                             }
                         },
                         "type": {
                             "required": false,
                             "type": "string",
                             "description": "Type of search. E.g: travel, dining,"
                         }
                     }
                 },
          ]
    }
}

Item APIs

The APIs in this section are for posting, getting, and deleting information related to items.

The following is the Orderly JSON format of the items object.

object {
    string id;
    string contextType;
    string owner;
    string provider;
    string clientCreatedTime;
    string serverCreatedTime;
    string serverModifiedTime;
    object value;
};

This table describes the fields of the items object.

Field Definition
id Item ID to be fetched.
contextType URN indicating the context type contained in the 'value' property. The value must match a type found in /typescatalog.
owner ID of the user who owns the data item.
provider IDs of the applications that generate the data item.
clientCreatedTime UTC time in ISO format that indicates when the client created the item.
serverCreatedTime UTC time in ISO format that indicates when the server created the item.
serverModifiedTime UTC time in ISO format that indicates when the server modified the item.
value The value of the context item, as described in the types catalog.

Query Stored Items

Querying /items returns results filtered by the caller's access permission and then by specified filter parameters (see table below).

Query responses have the same representation as responses from POST operations.

For examples of queries you can create with this API, see Query and Paginate Context Items. For examples that demonstrate GET /items calls, see Working with Context Types.

URL Structure

https://api.intel.com:8081/context/v1/items[?{params}]
Authorization: Bearer {access_token}

Method: GET

Input Parameters

Input Required Input Type Description
ids no string List of IDs to be fetched, separated by ampersands (&).
owners no string ID of the user who owns the data item.
contextTypes no URN Return data with a "contextTypes" attribute in a list separated by ampersands (&).
providers no string IDs, presented in a list, of the applications that generate the data item.
clientCreatedTimeBefore no UTC time in ISO format Return items that have a "clientCreatedTime" attribute earlier than the specified value.
clientCreatedTimeAfter no UTC time in ISO format Return items that have a "clientCreatedTime" attribute later than the specified value.
serverCreatedTimeBefore no UTC time in ISO format Return items that have a "serverCreatedTime" attribute earlier than the specified value.
serverCreatedTimeAfter no UTC time in ISO format Return items that have a "serverCreatedTime" attribute later than the specified value.
serverModifiedTimeBefore no UTC time in ISO format Return items that have a "serverModifiedTime" attribute earlier than the specified value.
serverModifiedTimeAfter no UTC time in ISO format Return items that have a "serverModifiedTime" attribute later than the specified value.
$filter no query language Indicates the beginning of a query.
$fields no fields Specifies the fields you would like returned by the query. Note that the ID field is always included in the response.
$limit no string Maximum number of items to return.
$offset no string Indicates the number of returned items to skip before listing the items that result from the query.
$orderby no enumeration Sets the sort order for items returned with GET call. As part of a query, orderby orders items in ascending order by default. You can set the order using the following:
orderby="field:asc"
orderby+"field:desc"
orderby="fiel1,field2:desc".

The following table lists the operators you can use in your Context Services queries. If an operator is not in this list, then it's not valid.

Operator Type Operator
Comparison $all
$gt
$gte
$in
$lt
$lte
$ne
$nin
Logical $and
$nor
$not
$or
Element $exists
$mod
Array $elemMatch
$size
Geospatial $box
$near
$within
$centerSphere
$center
$maxDistance
$nearSphere
$polygon
$uniqueDocs
JavaScript $regex

Example Usage

GET https://api.intel.com:8081/context/v1/items?clientCreatedTimeAfter=2012-01-19T17:20:00Z&clientCreatedTimeBefore=2012-01-19T17:30:00Z
Authorization: Bearer {access_token}

JSON Request

None

Response Codes

HTTP Code Message Description
200 OK The request was successful. An array of context items was returned.
401 Access Denied The caller does not have access to this item.
404 Not Found The resource does not exist.
500 Internal Error Servers are not working as expected. The request might be valid but needs to be retried later.

JSON Response

{
    "data": {
        "items": [
            {
                "id": "6e59f9e8db7311e183be0a407f65ef5d",
                "contextType": "urn:x-intel:context:type:location:current",
                "owner": "6d617474000000000000000000000001",
                "provider": "6d617474000000000000000000000000",
                "clientCreatedTime": "2012-01-19T17:23:15Z",
                "serverModifiedTime": "2012-08-01T00:54:21Z",
                "serverCreatedTime": "2012-08-01T00:54:21Z",
                "value": 
                    {"latitude":45.520082,"longitude": 122.676103,"accuracy":50}
             },
                                                                      ]
    }
}

Store New Items

Uploads data to Context Services by posting a set of context item structures to the /items collection.

Items with multiple data types can be included in the same POST.

ContextType, clientCreatedTime, and value are provided by the client; serverCreatedTime and serverModifiedTime are set by the service. Owner and provider need not be passed because they are taken from the request header.

All items in the post will be uploaded successfully, or none at all. On successful upload, the response is the completely specified object for each of the newly stored items, including a unique ID, server time stamps, and more. The order of the results matches the order of the uploaded values.

For examples that show posting items, including items that use the extension field, see Working with Context Types.

URL Structure

https://api.intel.com:8081/context/v1/items
Authorization: Bearer {access_token}

Method: POST

Input Parameters

Input Required Input Type Description
contextType yes URN URN indicating the context data type contained in the 'value' property. The value must match a resource type found in /typescatalog that has a "category" property of "context-type".
clientCreatedTime no UTC time in ISO format Returns items that have a "clientCreatedTime" attribute. If the clientCreatedTime parameter is not included in the call, the current time is used in its place.

Note: If you supply clientCreatedTime with an empty string value (""), it will be treated as an error. Doing so is not the same as omitting the parameter from the call.
value yes object The value that represents the clientCreatedTime.
extension no string JSON data that extends a standard context type. Can be used to make the context type more specific to the needs of apps.

Notes

The id, provider, serverCreatedTime, and serverModifiedTime fields must never appear in POST bodies. The credentials used with the request must allow the requester to post on the owner's behalf.

Example Usage

POST https://api.intel.com:8081/context/v1/items
Authorization: Bearer {access_token}

JSON Request

{
    "data": {
        "items": [
        { "contextType": "urn:x-intel:context:type:location:current",
          "clientCreatedTime": "2012-01-19T17:23:15Z",
            "value": 
                {"latitude":45.520082,"longitude": 122.676103,"accuracy":50}
           },
                              ]
    }
}

Response Codes

HTTP Code Message Description
201 Created The request was successful. Context information, or an array of context information, was posted.
401 Access denied The caller does not have the required permissions.
500 Internal Error Servers are not working as expected. The request might be valid but needs to be retried later.

JSON Response

{
    "data": {
        "items": [
            {
                "id": "6e59f9e8db7311e183be0a407f65ef5d",
                "contextType": "urn:x-intel:context:type:location:current",
                "owner": "6d617474000000000000000000000001",
                "provider": "6d617474000000000000000000000000",
                "clientCreatedTime": "2012-01-19T17:23:15Z",
                "serverModifiedTime": "2012-08-01T00:54:21Z",
                "serverCreatedTime": "2012-08-01T00:54:21Z",
                "value":
                   {"latitude":45.520082,"longitude": 122.676103,"accuracy":50}"
             },
                                                                       ]
    }
}

Delete Stored Items

Removes all context items that match the caller's access permission and query parameters.

URL Structure

https://api.intel.com:8081/context/v1/items[?{filter_params}]
Authorization: Bearer {access_token}

Method: DELETE

Input Parameters

Input Required Input Type Description
ids no string List of context item IDs to be deleted, separated by ampersands (&).
owners no string ID of the user who owns the data item.
contextTypes no URN Delete data with a "contextTypes" attribute in this comma-separated list.
providers no string IDs, presented in a list, of the applications that generate the data item.
clientCreatedTimeBefore no UTC time in ISO format Delete items that have a "clientCreatedTime" attribute earlier than the specified value.
clientCreatedTimeAfter no UTC time in ISO format Delete items that have a "clientCreatedTime" attribute later than the specified value.
serverCreatedTimeBefore no UTC time in ISO format Return items that have a "serverCreatedTime" attribute earlier than the specified value.
serverCreatedTimeAfter no UTC time in ISO format Delete items that have a "serverCreatedTime" attribute later than the specified value.
serverModifiedTimeBefore no UTC time in ISO format Delete items that have a "serverModifiedTime" attribute earlier than the specified value.
serverModifiedTimeAfter no UTC time in ISO format Delete items that have a "serverModifiedTime" attribute later than the specified value.

Example Usage

DELETE https://api.intel.com:8081/context/v1/items?contextTypes=urn:x-intel:context:type:location:checkin:v1;
Authorization: Bearer {access_token}

JSON Request

None

Response Codes

HTTP Code Message Description
204 No Content The request is complete. The response is empty.
401 Access denied The caller does not have access to the context item.
500 Internal Error Servers are not working as expected. The request might be valid but needs to be retried later.

JSON Response

None

Get Item (ID)

Gets the context information about a specific item, such as the item's context type, owner, ID, and client and server created times.

URL Structure

https://api.intel.com:8081/context/v1/items/{item_id}
Authorization: Bearer {access_token}

Method: GET

Input Parameters

Input Required Input Type Description
item_id yes string The ID of the content object.

Example Usage

GET https://api.intel.com:8081/context/v1/items/6e59f9e8db7311e183be0a407f65ef5d
Authorization: Bearer {access_token}

JSON Request

None.

Response Codes

HTTP Code Message Description
200 OK The request was successful. The context items was returned.
401 Access denied The caller does not have access to the context item.
404 Not found The item was not found.
500 Internal Error Servers are not working as expected. The request might be valid but needs to be retried later.

JSON Response

{
     "data": {
        "id": "6e59f9e8db7311e183be0a407f65ef5d",
        "contextType": "urn:x-intel:context:type:location:current",
        "owner": "6d617474-0000-0000-0000-000000000001",
        "provider": "6d617474-0000-0000-0000-000000000000",
        "clientCreatedTime": "2012-01-19T17:23:15Z",
        "serverModifiedTime": "2012-08-01T00:54:21Z",
        "serverCreatedTime": "2012-08-01T00:54:21Z",
        "value": 
        {"latitude":45.520082,"longitude": 122.676103,"accuracy":50}
    }
}

Delete Item (ID)

Deletes a specific item or items using the item's ID. Using query parameters removes all context items that match the caller's access permission and query parameters.

URL Structure

https://api.intel.com:8081/context/v1/items/{item_id}
Authorization: Bearer {access_token}

Method: DELETE

Input Parameters

Input Required Input Type Description
item_id yes string The ID of the context item to be deleted.

Example Usage

DELETE https://api.intel.com:8081/context/v1/items/6e59f9e8db7311e183be0a407f65ef5d
Authorization: Bearer {access_token}

JSON Request

None

Response Codes

HTTP Code Message Description
204 No content The request is complete. The response is empty.
401 Access denied The caller does not have access to the application instance information because it does not share the same owner.
410 Gone Non-existent item was deletd.
500 Internal Error Servers are not working as expected. The request might be valid but needs to be retried later.

JSON Response

None

Watch APIs

A client application can receive notifications when new data is posted to Context Services. By setting a "watch," you can specify the type of data you want to be notified about.

The watching application must have permissions and access to the new item, or a notification will not be generated. For more information, see GET /items/{item_id}.

The following is the Orderly JSON format of the watch object.

object {
    string id;
    string contextType;
    string owner;
    string provider;
    string callbackUrl;
};

This table describes the fields of the watch object.

Note: While the callbackURL is optional, including it in your watch objects will automatically generate a notification back to you whenever a new context item is added to the services that match your watch. If you do not include the callbackURL, you have to manually poll for newly added context.

Note also that the callbackURL must be publicly addressable.

Field Definition
id A unique identifier for the watch.
contextType The type of context, as provided in the types catalog.
owner User ID of the user who owns the watch item.
provider The application instance ID of the application that uploaded the watched data.
callbackURL URL for HTTP callback, used for asynchronous HTTP notification.

Get Watches

Returns the set of watch objects associated with the calling application. Each object represents a filter that will generate a notification to the caller.

URL Structure

https://api.intel.com:8081/context/v1/watches[?{query_params}]
Authorization: Bearer {access_token}

Method: GET

Input Parameters

Input Required Input Type Description
id no string The ID or list of IDs of the watch object.

Example Usage

GET https://api.intel.com:8081/context/v1/watches?id=4406e0ac08f511e2bea00a9b74ce8e68
Authorization: Bearer {access_token}

JSON Request

None

Response Codes

HTTP Code Message Description
200 OK The request was successful. An array of context watch objects was returned.
401 Access Denied The OAuth token was provided, but was invalid.
404 Not Found The resource does not exist.
500 Internal Error Servers are not working as expected. The request might be valid but needs to be retried later.

JSON Response

{ 
    "data": {
        "items": [{
            "id": "4406e0ac08f511e2bea00a9b74ce8e68"
            "contextType": "urn:x-intel:context:location:current",
            "owner": "6d617474000000000000000000000001",
            "provider: "6d617474000000000000000000000000",
            "callbackUrl": "http://api.intel.com:8081/context/v1/testcallback/1000"
       ]
    }
}

Create Watch

Creates a watch associated with the calling application. You can only create one watch by calling this URL.

You only need to provide contextType, owner, and provider. The callbackURL field is only needed if you want to use the asynchronous HTTP notification feature. The callbackUrl has to be in a valid URI format callable from the Internet.

Any one of the fields, contextType, owner, or provider, can be missing. Missing fields mean "don't care" or wildcard.

URL Structure

https://api.intel.com:8081/context/v1/watches
Authorization: Bearer {access_token}

Method: POST

Input Parameters

None

Example Usage

POST https://api.intel.com:8081/context/v1/watches
Authorization: Bearer {access_token}

JSON Request

{
    "data": {
        "contextType": "urn:x-intel:context:type:location:checkin:v1",
        "owner": "6d617474000000000000000000000001",
        "provider: "6d617474000000000000000000000000",
        "callbackUrl": "http://api.intel.com:8081/context/v1/testcallback/1000"      
    }
                                                          
}

Response Codes

HTTP Code Message Description
201 Created The request was successful. A context watch object was returned.
400 Bad Request A parameter is invalid or missing, or no OAuth token was provided.
401 Access Denied The OAuth token was provided, but is invalid.
409 Conflict The maximum number of watches (4) has been reached.
500 Internal Error Servers are not working as expected. The request might be valid but needs to be retried later.

JSON Response

{
    "data": {
        "contextType": "urn:x-intel:context:type:location:checkin:v1",
        "id": "4406e0ac08f511e2bea00a9b74ce8e68",
        "owner": "6d617474000000000000000000000001",
        "provider: "6d617474000000000000000000000000",
        "callbackUrl": "http://api.intel.com:8081/context/v1/testcallback/1000" 
    }
}

Get Watch (ID)

Uses a watch ID to get new context information for a specific watch.

URL Structure

https://api.intel.com:8081/context/v1/watches/{watch_id}
Authorization: Bearer {access_token}

Method: GET

Input Parameters

Input Required Input Type Description
watch_id yes string The ID of an existing watch.

Example Usage

GET https://api.intel.com:8081/context/v1/watches/106b1dae08f911e28fdf0a9b74ce8e68
Authorization: Bearer {access_token}

JSON Request

None

Response Codes

HTTP Code Message Description
200 OK The request was successful. A context watch object was returned.
404 Not found The watch was not found.
500 Internal Error Servers are not working as expected. The request might be valid but needs to be retried later.

JSON Response

{
    "data": {
        "contextType": "urn:x-intel:context:type:location:route",
        "id": "106b1dae08f911e28fdf0a9b74ce8e68",
        "owner": "6d617474000000000000000000000001",
        "provider: "6d617474000000000000000000000000",
        "callbackUrl": "http://api.intel.com:8081/context/v1/testcallback/1000"
    }
}

Delete Watch (ID)

Deletes a specific watch.

URL Structure

https://api.intel.com:8081/context/v1/watches/{watch_id}
Authorization: Bearer {access_token}

Method: DELETE

Input Parameters

Input Required Input Type Description
watch_id yes string The ID of an existing watch.

Example Usage

DELETE https://api.intel.com:8081/context/v1/watches/106b1dae08f911e28fdf0a9b74ce8e68
Authorization: Bearer {access_token}

JSON Request

None

Response Codes

HTTP Code Message Description
204 Deleted The request was successful. The watch was deleted.
401 Access Denied The application does not have permission to delete the watch.
410 Gone The watch does not exist.
500 Internal Error Servers are not working as expected. The request might be valid but needs to be retried later.

JSON Response

None

Get New Items that Match Watches

Returns new items for watches that have been set. Gets the new context items created since the last time a GET of /watches/newitems was performed. The /watches/newitems resource is a dynamic view on the /items resource. It contains context items contained in /items where all of the following are true:

  • The context item properties match one of the watch patterns in the /watches resource.
  • The user who created the watch has access to the new context items.

Context items are returned to the caller in the order in which they are posted to Context Services. When a context item is returned to the caller, it is removed from the /watches/newitems resource. The caller will never receive the same context item twice from subsequent GETs. The data returned to the caller has the same format as data returned from a GET of /items.

URL Structure

https://api.intel.com:8081/context/v1/watches/newitems
Authorization: Bearer {access_token}

Method: GET

Input Parameters

None

Example Usage

GET https://api.intel.com:8081/context/v1/watches/newitems
Authorization: Bearer {access_token}

JSON Request

None

Response Codes

HTTP Code Message Description
200 OK The request was successful. An array of context items was returned.
401 Access Denied The OAuth token was provided but was invalid.
404 Not Found The resource does not exist.
500 Internal Error Servers are not working as expected. The request might be valid but needs to be retried later.

JSON Response

{
    "data": {
        "items": [
            {
                "id": "6e59f9e8db7311e183be0a407f65ef5d",
                "contextType": "urn:x-intel:context:type:location:current",
                "owner": "6d617474000000000000000000000001",
                "provider": "6d617474000000000000000000000000",
                "clientCreatedTime": "2012-01-19T17:23:15Z",
                "serverModifiedTime": "2012-08-01T00:54:21Z",
                "serverCreatedTime": "2012-08-01T00:54:21Z",
                "value": 
                    {"latitude":45.520082,"longitude": 122.676103,"accuracy":50}
             },
         ]
    }
}

Behavior Model APIs

Context Services can create models that characterize user habits based on information reported to the service. The models are based on sequences of events, each of which describes the transition from one context instance to the next. The models/behavior APIs provide the following:

  • Possible next destinations based on past user location visits and time of visit information.
  • A list of cuisine options likely to appeal to a user based on past restaurant-related context gathered for the user.
  • A user's place, based on current location and routes information.
  • A user's predicted activity, based on the timestamp for the call.

List Possible Next Destinations

Lists the next possible location that the user might go by analyzing context that was gathered for that user.

URL Structure

https://api.intel.com:8081/context/v1/users/{userid}/models/behavior/places?lat={x}&lon={y}&timestamp={ts}
Authorization: Bearer {access_token}

Method: GET

Input Parameters

Input Required Input Type Description
userid yes string The ID of the user in the authentication token. You can also substitute "me ."
lon yes decimal degrees Longitude in degrees for the starting location.
lat yes decimal degrees Latitude in degrees for the starting location.
timestamp yes UTC time in ISO format Time when the event begins.

Example Usage

GET https://api.intel.com:8081/context/v1/users/{userid}/models/behavior/places?lat=45.539211&lon=-122.8932&timestamp=2012-09-05T08:20:05Z
Authorization: Bearer {access_token}

JSON Request

None

JSON Response

{
    "distance-factor": 0.232717611823722,
    "centroid": {
        "lon": -122.973328533333,
        "lat": 45.5199697333333
    },
    "weight": 7.56332238427096,
    "place-id": "abc10613-df3f-450c-b32a-f9168e14f291",
    "poi-type": "restaurant"
},

Get Point of Interest Weights from Behavior Model

Queries the model for point of interest attributes, particularly related to cuisine. Time and location parameters are optional, but including them improves the quality of the prediction.

URL Structure

https://api.intel.com:8081/context/v1/users/{userid}/models/behavior/poi-weights?lat={x}&lon={y}&timestamp={ts}
Authorization: Bearer {access_token}

Method: GET

Input Parameters

Input Required Input Type Description
userid yes string The ID of the user in the authentication token. You can also substitute "me ."
lat no (lat should be included with lon) decimal degrees Latitude in degrees forthe location for which you want POI.
lon no (lon should be included with lat) decimal degrees Longitude in degrees for the location for which you want the POI.
timestamp no UTC time in ISO format Time of day when you want the suggestion for weighted POI.

Example Usage

GET https://api.intel.com:8081/context/v1/users/me/models/behavior/poi-weights?lat=45.54&lon=-122.9623&timestamp=2012-11-10T09:08:07Z
Authorization: Bearer {access_token}

JSON Request

None

Response Codes

HTTP Code Message Description
200 OK The request was successful.
401 Access denied The caller does not have access to the application instance information.
404 Not found The user was not found.
500 Internal error Servers are not working as expected. The request might be valid but needs to be retried later.

JSON Response

[
    {
        "weight" : 67.91666666666667,
        "attributes" : {
            "price" : 1,
            "cuisine" : "Japanese"
        }
    },
    {
         "weight" : 54.375,
         "attributes" : {
             "price" : 1,
             "cuisine" : "Cafe"
        }
    },
    {
         "weight" : 22.29166666666667,
         "attributes" : {
             "price" : 2,
             "cuisine" : "French"
        }
    }
]

Get Place

Based on the user's current location or route, predicts where the user is. Currently predicts whether the user is at work or at home. This API can be used to personalize your apps to behave differently depending on whether the user is at work or at home.

This API relies on your user granting permission via the prediction:location-id scope.

URL Structure

GET https://api.intel.com:8081/context/v1/users/me/models/behavior/place/home

or

GET https://api.intel.com:8081/context/v1/users/me/models/behavior/place/work

Input Parameters

None

Example Usage

GET https://api.intel.com:8081/context/v1/users/me/models/behavior/place/home
Authorization: Bearer {access_token}

JSON Request

None

Response Codes

HTTP Code Message Description
200 OK The request was successful.
401 Access Denied The OAuth token was provided but was invalid.

JSON Response

The response provides the place-id that's assigned to either a user's home or work.

[
    {
        "place-id" : "6f4f160e-885f-435c-bb9a-301bb09496d4",
        "centroid" : {
            "lon" : -122.96345600000016,
            "lat" : 45.54337799999998
        }
    }
]

Predict Activity

Predicts what the user is doing based on the time of day. Currently the behavior model predicts either sleeping or working. This information can be useful for tasks like data processing that you would prefer to set for times when the user is sleeping.

This API relies on your user granting permission via the prediction:activity scope.

URL Structure

GET https://api.intel.com:8081/context/v1/users/me/models/behavior/activity{timestamp}

Input Parameters

Input Required Input Type Description
timestamp yes UTC time in ISO format Timestamp that includes the date, time, seconds and time zone.

Example Usage

GET https://api.intel.com:8081/context/v1/users/me/models/behavior/activity?timestamp=2013-04-01T11%3A00%3A00.000-0700
Authorization: Bearer {access_token}

JSON Request

None

Response Codes

HTTP Code Message Description
200 OK The request was successful.
400 Bad request Parameter is invalid or missing.
401 Access Denied The OAuth token was provided but was invalid.

JSON Response

The timestamp indicates that it's the middle of the night, so the prediction is:

[
    "sleeping"    
]

Response Codes and Error Handling

When errors are detected during an API call, the error information is returned in the body of the response, as follows:

{
“code” : “XXX-nnnnn”,
“transactionid”: “c962fe29-d4e8-11e1-bd04-0050568c00f9”,
“message” : “Description of error message”
}

The following table is a list of error codes returned by the Context Services REST interface. A subset of the errors can be returned for each call.

HTTP Code Message Description
200 OK The request was a success.
201 Created The newly created policy.
204 No Content Empty body.
400 Bad request Any case where a parameter is invalid or a required parameter is missing. This includes the case where no OAuth token is provided.
401 Access Denied The OAuth token was provided but was invalid.
403 Forbidden The caller does not have access to the application instance information because the caller does not share the same owner.
404 Not found Resource does not exist.
405 Method not allowed Attempting to use any other method different than GET.
409 Conflict Response when you attempt to create more than four watches per instance.
410 Gone Non-existent item or watch deleted.
500 Internal server error Servers are not working as expected. The request might be valid but needs to be retried later.

More Context Services Information

Context Services REST Developer's Guide

Set a Watch for New Context

Use the Behavior Model to Forecast User Behavior

Working with Context Types

Query and Paginate Context Items

Context Services Interactive Demo