Chart Annotations
A chart annotation is a note the user has written against a measurement at a point in time, such as what caused a glucose spike. It is anchored by a data field and an instant rather than by an item, so every chart plotting that measurement over that instant shows it.
The data field is canonicalized when the note is written. A note created against DISTANCE_IN_MILES is stored and returned as DISTANCE_IN_KM, which is what lets one note appear on charts drawn in either unit. The Descriptions API with a type of dataFields lists the fields available.
A calculated measurement takes no note. GLUCOSE_ESTIMATED_A1C, GLUCOSE_PERCENT_IN_RANGE, SLEEP_DEBT and the cycle predictions are worked out from other readings rather than recorded, so there is no reading to annotate.
Listing Chart Annotations
This method lists the notes the user has written, oldest first.
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/annotations/"| Query Parameter Name | Description |
|---|---|
| offset | How many entries should we skip? Default is 0. |
| limit | How many entries would you like to return? Default and max is 100. |
| startDate | Earliest note to return, in milliseconds since the epoch. 0, the default, means no lower bound. |
| endDate | Latest note to return, in milliseconds since the epoch. 0, the default, means no upper bound. |
| dataField | Restrict to notes on these measurements. Repeat the parameter for more than one, and omit it for every measurement. Fields are canonicalized before matching, so asking for DISTANCE_IN_MILES also returns notes written against DISTANCE_IN_KM. |
Response
The HTTP Response Code will be a 200 on success and the body will be an Annotation List.
Get a Chart Annotation
This method gets one note by id.
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/annotations/id"Request Parameters
None
Response
The body with an Annotation, or a 404 when there is no note with that id.
Create a Chart Annotation
This method writes a new note. The dataField, date and note properties are required; everything else on the body is assigned by FitnessSyncer and ignored on the way in.
Request Parameters
A body containing an Annotation
Response
The body with the created Annotation, including the id assigned to it.
Update a Chart Annotation
This method changes the text or the date of a note. Send only the properties being changed; anything omitted is left as it is.
The measurement is fixed when the note is written and cannot be changed here, because moving a note to a different measurement would relocate it onto charts the caller never named. Write a new note and delete the old one instead.
Request Parameters
A body containing an Annotation
Response
The body with the updated Annotation.
Delete a Chart Annotation
This method deletes a note.
Example request
curl -X DELETE -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/annotations/id"Request Parameters
None
Response
The HTTP Response Code will be a 200 on success, or a 404 when there is no note with that id.
Types
Annotation
| JSON Item | Data Type | Description |
|---|---|---|
| id | String | Unique id of the annotation, assigned when it is written. Read-only. |
| dataField | String | The measurement the annotation is about. Canonicalized on write, so an annotation created against one unit of a measurement reads back as that measurement’s canonical field and appears on charts drawn in either unit. See the Descriptions API with a type of dataFields for the accepted values. |
| taskType | String | The type of data the measurement belongs to, derived from dataField. Must be one of the TaskType values. Read-only. |
| date | Long | The instant the annotation is about, in milliseconds since the epoch. On an annotation written from a chart this is the start of the bucket that was clicked, not the moment of writing. |
| annotation | String | The text of the annotation. Trimmed, and truncated at 1000 characters. |
| created | Long | When the annotation was first written, in milliseconds since the epoch. Read-only. |
| modified | Long | When the annotation was last changed, in milliseconds since the epoch. Read-only. |
Annotation List
| JSON Item | Data Type | Description |
|---|---|---|
| items | Array of Annotation | The annotations, oldest first. |
