### CONTENTS
1. Authentication
2. Observations API
3. Data
# 1. Authentication
OAuth 2.0 is used for authorizing the API calls. In order to access users data via the API, one needs to first receive an access token. Then this access token needs to be included either as a query parameter or in the headers.
## 1.1 Receiving an access_token and userId (patient.id)
`POST /api/auth`
body:
{"username":"user@example.com","password":"secret"}
CURL example:
curl -H "Content-Type: application/json" -d '{"username":"user@example.com","password":"secret"}' https://www.measuretomotivate.philips.com//api/auth
**Response:**
{
"access_token": "1f964f74ea84e50663cde2f2d888d60f7878b6b089c1e7274c3d44270a69aa8d",
"refresh_token":
"a7c0f36d2d737b8adcb839aebbbed03943dae6375edcf77de2146fc53db4369df5532a7a989dc35b168b0eaa67c36db16ceebe9ec72fe1dbd155b0280274b61f",
"token_type": "bearer",
"userID": "1"
}
In case of a successful login, you get an access token back giving you authentication and authorization. Additionally, you get the userId which you can use in the URIs of thesubsequent API calls to the platform. You need to include this token in each and every consecutive request APIs to confirm the authentication.
## 1.2. Signing API requests with an access token
As a query parameter:
`GET /api/fhir/Patient/:userID?access_token=[access_token]`
CURL example:
curl -H 'Content-Type: application/json' https://www.measuretomotivate.philips.com//api/fhir/Patient/:userId?access_token=1f964f74ea84e50663cde2f2d888d60f7878b6b089c1e7274c3d44270a69aa8d
In the headers:
Set 'Authorization' header to 'bearer [access_token]'
CURL example:
curl -H 'Content-Type: application/json' -H 'Authorization: bearer 1f964f74ea84e50663cde2f2d888d60f7878b6b089c1e7274c3d44270a69aa8d' https://www.measuretomotivate.philips.com//api/fhir/Patient/1
# 2. Observations API
## 2.1 Get observations for a user (patient)
- This is the endpoint where a series of a particular observation type (weight for example) can be retrieved for a specific period of time
- The resulting values are calculated, based on the type of the observation. Cumulative observations (like “steps”) are summed, while individual measurements (like “weight”) return the latest value per resolution interval.
- One possible usage could be to plot entries on a UI chart.
- resolution is not availbale for FHIR format
For example:
- “steps” returns the summed number of steps per resolution chunk.
- “bloodpressure” returns the latest measurement per resolution chunk.
- “heartrate” returns the average heart rate per resolution chunk.
- “sleepduration” returns the duration of the longest sleep session, ending in the resolution chunk
### FHIR format
`GET /api/fhir/Observation?type=[type]&start=[start]&end=[end]&patient.id=[userId]`
For response format see [FHIR format](https://www.hl7.org/fhir/). Since observations API retrieves multiple observations for a period of time, these are returned as a part of [FHIR 'bundle']
(https://www.hl7.org/fhir/bundle.html). The array of entries of this bundle are the (aggregated) observations for the requested period with each one being a [FHIR 'observation' resource]
(https://www.hl7.org/fhir/observation.html).
For some observation types such as 'feeding' and 'bloodpressure' observations are also organized in components.
### REST format
`GET /api/users/:userId/observations/:type?start=[start]&end=[end]?resolution=[resolution]`
The general format of the API response is:
{
“yyyy-MM-dd” : {
“offset_seconds” : {“v”:
“offset_seconds” : {“v”: <value>, d: <duration_seconds>},
…
},
“yyyy-MM-dd” : {
“offset_seconds” : {“v”: <value>, d: <duration_seconds>},
“offset_seconds” : {“v”: <value>, d: <duration_seconds>},
},
…. }
The duration (d) is optional and provided only in case of observations that support a duration (e.g.: sleepduration).
A metrics with no duration and default resolution, for example:
`GET /api/users/:userId/observations/weight?start=2014-11-25T00:00:00&end=2014-11-27T00:00:00`
**Response:**
{
"2014-11-25" : {
"32460" : {“v”: 71.2}, // 9:01 AM, measured 71.2 kg
"39720" : {“v”: 71.5} // 11:02 AM
},
"2014-11-26" : {
"36060" : {“v”: 70.9} // 10:01 AM
}
}
A metric with a duration and default resolution, for example:
`GET /api/users/:userId/observations/calories /?start=2014-11-25T00:00:00&end=2014-11-27T00:00:00`
**Response:**
{
"2014-11-25" : { // kcal burned in a minute
"6000" : {“v”: 1.2, “d”: 60},
"6060" : {“v”: 1.039, “d”: 60},
…
},
"2014-11-26" : {
"1200" : {“v”: 1.432, “d”: 60},
"1260" : {“v”: 0.34, “d”: 60},
…
}
}
Setting the resolution to daily level, for example:
GET /api/users/:userId/observations/calories?start=2014-11-25T00:00:00&end=2014-11-27T00:00:00&resolution=86400
**Response:**
{
"2014-11-25" : { // kcal burned in a day
"0" : {“v”: 2103.3, “d” : 86400}
},
"2014-11-26" : {
"0" : {“v”: 1788.4, “d” : 86400}
}
}
## 2.1.1 Parameters
### 'Start' and 'end'
- required
- These are start and end dates of the period for which observations will be retrieved;
- The only accepted format is 'YYYY-MM-DDTHH:mm', for example, '2014-11-25T12:00'
- All times are in UTC
### 'Type'
- required
Supported types:
- 'weight' (retrieved with minute resolution)
- 'steps' (retrieved with minute resolution)
- 'calories' (retrieved with minute resolution)
- 'energyintake' (retrieved with minute resolution)
- 'heartrate' (retrieved with minute resolution)
- 'restingheartrate' (retrieved with minute resolution)
- 'bloodpressure' (retrieved with minute resolution)
- 'skintemperature' (retrieved with minute resolution)
- 'bloodglucose' (retrieved with minute resolution)
- 'fatpercentage' (retrieved with minute resolution)
- 'hba1c' (retrieved with minute resolution)
- 'feeding' (retrieved with minute resolution)
- 'sleepduration' (retrieves durations of sleep intervals ending inside the requested time period)
### userId (patient.id)
- required
- userId and patient.id are the same
- please see "1.1 Receiving an access_token and userId" on how to get the userId
### resolution
- optional
- not available for FHIR
- granularity in seconds of the returned data points. Default is 60 seconds.
- minimal available is 60 seconds
- if invalid will default to 60 seconds
## 2.2 Retrive a single observation by id:
`GET /api/fhir/Observation/:observationId`
**Response:**
{
"resourceType": "Observation",
"status": "final",
"reliability": "ok",
"appliesPeriod": {
"start": "2015-01-04T00:19:00+00:00",
"end": "2015-01-04T06:53:00+00:00"
},
"name": {
"coding": [ {
"system": "http://browser.ihtsdotools.org/",
"code": "248263006",
"display": "Duration of sleep"
}
]
},
"valueQuantity": {
"units": "s",
"system": "http://unitsofmeasure.org",
"value": 23640
},
"id": "1:sleepduration:86400:1420329600:1420416000"
}
## 2.3 Examples
#### Example 1: retrieve weight observations for patient 1 from 2015-03-22T15:00 until 2015-03-25T15:00
`GET /api/fhir/Observation?patient.id=1&type=weight&start=2015-03-22T15:00&end=2015-03-25T15:00 &access_token=[access_token]`
**Response:**
"resourceType": "Bundle",
"title": "Multiple observations",
"total": 3,
"link": [
{
"rel": "self",
"href": "https://www.measuretomotivate.philips.com//api/fhir/Observation?patient.id=1&type=weight&start=2015-03-22T15:00&end=2015-03-25T15:00"
}
],
"entry": [
{
"content": {
"subject": {
"reference": "Patient/1"
},
"resourceType": "Observation",
"status": "final",
"reliability": "ok",
"appliesDateTime": "2015-03-23T06:39:00+00:00",
"name": {
"coding": [
"system": "http://loinc.org",
"code": "3141-9",
"display": "Weight measured"
}
]
},
"valueQuantity": {
"units": "kg",
"system": "http://unitsofmeasure.org",
"code": "kg",
"value": 73.8323
"id": "1:weight:60:1427092740:1427092800"
}
},
"content": {
"subject": {
"reference": "Patient/1"
},
"resourceType": "Observation",
"status": "final",
"reliability": "ok",
"appliesDateTime": "2015-03-24T06:32:00+00:00",
"name": {
"coding": [
{
"system": "http://loinc.org",
"code": "3141-9",
"display": "Weight measured"
}
]
},
"valueQuantity": {
"units": "kg",
"system": "http://unitsofmeasure.org",
"code": "kg",
"value": 74.5564
},
"id": "1:weight:60:1427178720:1427178780"
}
},
{
"content": {
"subject": {
"reference": "Patient/1"
},
"resourceType": "Observation",
"status": "final",
"reliability": "ok",
"appliesDateTime": "2015-03-25T06:32:00+00:00",
"name": {
"coding": [
"system": "http://loinc.org",
"code": "3141-9",
"display": "Weight measured"
}
]
},
"valueQuantity": {
"units": "kg",
"system": "http://unitsofmeasure.org",
"code": "kg",
"value": 76.3873
},
"id": "1:weight:60:1427265120:1427265180"
}
}
]
}
#### Example 2: retrieve sleep duration for patient 1 in (Amstedam/Netherlands timezone ) for 2015-03-23
* the API returns the sleep duration of the sleep intervals ending in the requested period of time
`GET /api/fhir/Observation?patient.id=1&type=sleepduration&start=2015-03-22T22:00&end=2015-03-23T22:00`
**Response:**
{
"resourceType": "Bundle",
"title": "Multiple observations",
"total": 1,
"link": [
{
"rel": "self",
"href": "https://www.measuretomotivate.philips.com//api/fhir/Observation?patient.id=1&type=sleepduration&start=2015-03-22T22:00&end=2015-03-23T22:00"
}
],
"entry": [
{
"content": {
"subject": {
"reference": "Patient/1"
},
"resourceType": "Observation",
"status": "final",
"reliability": "ok",
"appliesPeriod": {
"start": "2015-03-22T21:19:00+00:00",
"end": "2015-03-23T06:20:00+00:00"
},
"name": {
"coding": [
{
"system": "http://browser.ihtsdotools.org/",
"code": "248263006",
"display": "Duration of sleep"
}
]
},
"valueQuantity": {
"units": "s",
"system": "http://unitsofmeasure.org",
"value": 32460
},
"id": "1:sleepduration:86400:1426982400:1427068800"
}
}
]
}
#### Example 3: retrieve feeding data for patient 3 from 2015-06-04T00:00 until 2015-06-04T14:00
* observations are grouped inside of a component, because they all belong to the same feeding
`GET /api/fhir/Observation?patient.id=3&type=sleepduration&start=2015-03-22T22:00&end=2015-03-23T22:00`
**Response:**
"resourceType": "Bundle",
"title": "Multiple observations",
"total": 1,
"link": [
{
"rel": "self",
"href": "https://www.measuretomotivate.philips.com//api/fhir/Observation?patient.id=3&type=feeding&start=2015-06-04T00:00&end=2015-06-04T14:00"
}
],
"entry": [
{
"content": {
"subject": {
"reference": "Patient/3"
},
"resourceType": "Observation",
"status": "final",
"reliability": "ok",
"appliesDateTime": "2015-06-04T13:14:10+00:00",
"code": {
"coding": [
{
"system": "http://browser.ihtsdotools.org/",
"code": "129007004",
"display": "Baby feeding from a bottle"
}
]
},
"component": [
{
"name": {
"coding": [
{
"display": "Bottle content"
}
]
},
"valueQuantity": {
"value": "Formula milk"
}
},
{
"name": {
"coding": [
{
"display": "Feeding performer"
}
]
},
"valueQuantity": {
"value": "Mother"
}
},
{
"name": {
"coding": [
{
"display": "Overall score"
}
]
},
"valueQuantity": {
"value": 5
}
},
{
"name": {
"coding": [
"display": "Happiness score"
}
]
},
"valueQuantity": {
"value": 5
}
},
{
"name": {
"coding": [
{
"display": "Feeding duration"
}
]
},
"valueQuantity": {
"units": "s",
"system": "http://unitsofmeasure.org",
"value": 469.66
}
},
{
"name": {
"coding": [
{
"display": "Average temperature of bottle contents"
}
]
},
"valueQuantity": {
"units": "deg C",
"system": "http://unitsofmeasure.org",
"value": 36.8198
}
},
{
"name": {
"coding": [
{
"display": "Average environmental light"
}
]
},
"valueQuantity": {
"units": "lx",
"system": "http://unitsofmeasure.org",
"value": 111.505
}
},
{
"name": {
"coding": [
{
"display": "Average noise level"
}
]
},
"valueQuantity": {
"units": "dB",
"system": "http://unitsofmeasure.org",
"value": 50.3617
}
},
{
"name": {
"coding": [
{
"display": "Number of brakes"
}
]
},
"valueQuantity": {
"value": 2
}
},
{
"name": {
"coding": [
{
"display": "Duration of brakes"
}
]
},
"valueQuantity": {
"units": "s",
"system": "http://unitsofmeasure.org",
"value": 169.924
}
}
],
"id": "3:feeding:60:1433423640:1433423700"
}
}
]}
... more examples to come
# 3. Data
Here is the list of data per persona currently available.
### 3.1. Diabetes Patient, for 1 year: 2014-09-22 - 2015-09-22
- blood glucose,
- blood pressure,
- burned calories,
- energy intake,
- fat percentage,
- hba1c (glycohemoglobin),
- heart rate,
- resting heart rate,
- skintemperature,
- sleep duration,
- steps,
- weight
### 3.2. Healthy person, for 1 year: 2014-09-22 - 2015-09-22
- blood pressure,
- burned calories,
- energy intake,
- fat percentage,
- heart rate,
- resting heart rate,
- skintemperature,
- sleep duration,
- steps,
- weight
### 3.3. Baby, for 1 month: 2015-05-19 - 2015-06-08
- Feeding performer
- Bottle content
- Overall score
- Happiness score
- Bottle initial weight
- Bottle end weight
- Feeding duration
- Bottle contents avg temperature
- Average environmental light
- Average noise level
- Number of brakes
- Duration of brakes
You are about to visit a Philips global content page
Continue