Requests and responses

Sony’s Lifelog API will be closed down at the end of May 2017. From that point, no further usage will be possible.

We apologize for any inconvenience caused.

You can keep up with our other API releases and updates here.

On this page you can learn how to make requests to the Lifelog API, from what the mandatory parameters are to available options. You will also find information on how to interpret and organize the response you get from the Lifelog platform.

How to format requests: versions and extensibility

Each endpoint accesses data for the current user, and is prefixed with a version identifier (v1 here).

GET /v1/users/me

As API development continues, new fields may be added to a version, as long as the changes are backward compatible. If fields are removed or the field semantics change, a new API version will be made available.

Required HTTPS headers

All requests must be authorized. Provide the current user’s OAuth2 access token in the Authorization header:

Authorization: Bearer <token>

All data is returned in the body of the response in JSON format. You must set the Accept header accordingly:

Accept: application/json

Specify GZIP compression for the response using the Accept-Encoding header, and for the request using the Content-Encoding header:

Accept-Encoding: gzip	 	 
Content-Encoding: gzip

Data formats and conventions

The following data formats and conventions are used in the API:

  • Data values : The Lifelog API generally adheres to the international system of units (SI) for returned data values. For some fields it makes more sense to use a non-SI unit; for example, energy expenditure uses kilo-calories instead of joules.
  • Date-time format : All timestamps must be specified as ISO 8601 complete date-times, with hours, minutes, seconds with three decimals and time zone (YYYY-MM-DD’T’hh:mm:ss.sssTZD). For example:
    2014-04-10T10:18:19.624Z          
    2014-04-10T14:58:25.064+0100

    See the W3C webpage for more information.

  • ID Format : Most Lifelog data items can be specifically referenced with a unique ID. Identifiers resemble a standard UUID, but you should always treat them as strings. The actual value may not always be compatible with the UUID specification, although they are guaranteed to be globally unique.To retrieve an individual entry, append the ID string to the UID. For example:
    GET /v1/users/me/activities/ba2e7500-e022-4daf-817b-1e607e0cff43-2014-06-01

You can use the Lifelog API to request an individual activity or location entry directly using its unique ID, or you can get a collection of activities or locations.

Specifying a time range

All activities and locations are associated with times, so a query typically specifies a time period of interest. To request entries that occurred within a certain time period, add these query parameters to the request to specify the time period.

Parameter Value Description
start_time Timestamp The time stamp of the earliest entry to include. If omitted, all entries before end time are returned.
end_time Timestamp The time stamp for the end of the period. Entries with this time stamp are excluded. If omitted, all available entries after start time are returned.

Here is an example of a request for activities entries that occurred during a specific time period:

GET /v1/users/me/activities?start_time=2014-06-09T09:00:00.000Z&end_time=2014-06-09T10:00:00.000Z

The requested entries are returned in chronological order.

Response format

The response to your request contains a result section and a links section. On a high level, it looks like this:

{
   "result" : [
        ... items ...
   ],
   "links" : [
        ... links ...
   ]
}

The result section contains the details of the requested data item, or of each activity or location that was logged within the requested time period. All data is returned as a set of JSON objects. For example, if the user has logged the “walk” activity, the data contained in the response body (for a single entry) might look like this:

{
   "result" : [
      {
         "id" : "ba2e7500-e022-4daf-817b-1e607e0cff43",
         "type" : "physical",
         "subtype" : "walk",
         "sources" : [
            {
               "name" : "Lifelog",
               "id" : "42ad35b065e880a3",
               "type" : "phone"
            }
         ],
         "startTime" : "2014-06-09T10:54:00.000+01:00",
         "endTime" : "2014-06-09T10:57:00.000+01:00",
         "details" : {
            "steps" : [ 20, 28, 19 ],
            "distance" : [ 13.662, 19.1268, 12.9789 ],
            "aee" : [ 2.1361, 2.1361, 2.1361 ],
            "tee" : [ 3.1361, 3.1361, 3.1361 ]
         }
      }
   ]
}

If you expect a large amount of data, you can request that the result be returned in a set of pages of a specified size. If you do this, the links section of the response points to the additional pages, as described below.

Limiting and paginating results

Requests for activities and location data allow you to limit the amount of data returned in a single response. The following request, for example, includes the limit query parameter, specifying that no more that 25 items should be returned:

GET /v1/users/me/activities?start_time=2014-05-08T09:00:00.00Z&end_time=2014-05-08T10:00:00.00Z&limit=25

If there are 25 or fewer result items available, they are simply returned in the result section of the response. However, if more than 25 items are available, they are returned in one or more pages of the specified size at a temporary URL. The link is returned in the links section of the original response; if more than one additional page is returned, there can be multiple links. For example:

{
  "result" : [
    ... first page of data ...
   ],
  "links" : [
    {
    "rel" : "next",
    "href" : "https://.../users/me/activities?v=0&limit=25&page=McgGHdfghdCBNSIsfaW"
    }
  ]
}

You can fetch the next set of data  using these links, as defined in the latest JSON schema. The page parameter in the href property is an arbitrary text string that you use to retrieve the next page of data. Do not store the URL or page value. It is only valid for a limited time.

Data is returned in chronological order, with the newest item returned first.

Error response format

If an error is encountered, the returned JSON structure contains the error information instead of retrieved data:

{
    "error" : {
        "code" : <see table of error codes below>
        "message" : <description of error – not always present, not meant for display>
    }
}

These errors can be returned:

HTTP Status Code Description
403 AccessDenied You do not have permission to access the requested resource. The error message may contain more information on why access was denied.
401 InsufficientAuthentication No access token was provided, or the provided access token was invalid. The error message may contain more information.
404 ResourceNotFound The requested resource does not exist.
422 UnprocessableEntity The request could not be parsed or contained invalid values. The error message contains more information about which fields were invalid.