Timeseries

The Timeseries endpoint allows you to retrieve time-series data for various biometric signals.

GET /v1/timeline/timeseries/{user_id}/{mtype}

Parameters

Name	Type	In	Description
`user_id`	UUID	Path	The unique identifier for the user.
`mtype`	Enum	Path	The type of measurement to retrieve. See Measurement Types for allowed values.
`start_date`	Date	Query	The start date for the query period (format: `YYYY-MM-DD`).
`end_date`	Date	Query	The end date for the query period (format: `YYYY-MM-DD`).
`days`	Integer	Query	Days per page (default `1`, max `7`). Only applies to `application/json` cursor-based pagination.
`cursor`	String	Query	Pagination cursor from the previous response. Only supported on `application/json`; returns `400` for CSV and Parquet.

Response Formats

You can specify the desired response format using the Accept header.

Header Value	Format
`application/json`	JSON (default)
`text/csv`	CSV
`application/octet-stream`	Apache Parquet

Response Status Codes

200 ok

The request was successful. A date range with no data returns 200 with empty arrays in data.

404 not found

The user ID was not found.

{
    "type": "about:blank",
    "title": "Not Found",
    "status": 404,
    "detail": "No measurement HEART_RATE for user between 2024-04-01 and 2024-04-02 found in database",
    "instance": "/v1/timeline/timeseries/YOUR_USER_ID/HEART_RATE",
    "code": "not_found",
    "request_id": "3a7b2c1d-..."
}

429 too many requests

Rate limit exceeded. Honour the Retry-After header before retrying.

Measurement Types

`HEART_RATE`

Continuous Heart Rate, measured in beats per minute (bpm).

Granularity: 10 seconds
Quality Indicator: 1 to 4 (4 = best).

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/HEART_RATE?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "timestamp": ["2024-04-01T12:00:00Z", "2024-04-01T12:00:10Z"],
        "value": [65, 66],
        "quality": [4, 4]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/HEART_RATE?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

timestamp,value,quality
2024-04-01T12:00:00Z,65,4
2024-04-01T12:00:10Z,66,4

`ACTIVITY_COUNT`

A measure of movement. Higher values indicate greater movement.

Granularity: 1 second

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/ACTIVITY_COUNT?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "timestamp": ["2024-07-01T00:00:04Z", "2024-07-01T00:00:05Z"],
        "value": [52, 54]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/ACTIVITY_COUNT?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

timestamp,value
2024-07-01T00:00:04Z,52
2024-07-01T00:00:05Z,54

`ACTIVITY_TYPE`

Categorical activity type.

Since the granularity is 1 second, the ACTIVITY_TYPE endpoint only returns values when there is either a change in the type or a change in the quality occurs. To retrieve the 1 second granularity you must forward fill the data.

Granularity: 1 second
Values: UNSPECIFIED, OTHER, WALK, RUN, CYCLE, REST

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/ACTIVITY_TYPE?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "timestamp": ["2024-04-01T12:00:00Z", "2024-04-01T12:00:01Z"],
        "value": ["REST", "WALK"],
        "quality": [4, 3]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/ACTIVITY_TYPE?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

timestamp,value,quality
2024-04-01T12:00:00Z,REST,4
2024-04-01T12:00:01Z,WALK,3

`STEPS`

Number of steps detected. Steps are sent from the watch in batches when at least 12 new steps are recorded since the previous batch.

Granularity: Event-based

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/STEPS?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "timestamp": ["2024-04-01T12:05:10Z", "2024-04-01T12:05:45Z"],
        "value": [15, 25]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/STEPS?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

timestamp,value
2024-04-01T12:05:10Z,15
2024-04-01T12:05:45Z,25

`SKIN_TEMPERATURE`

Skin temperature, measured in Celsius.

Granularity: 5 seconds

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/SKIN_TEMPERATURE?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "timestamp": ["2024-04-01T12:00:00Z", "2024-04-01T12:00:05Z"],
        "value": [34.5, 34.6]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/SKIN_TEMPERATURE?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

timestamp,value
2024-04-01T12:00:00Z,34.5
2024-04-01T12:00:05Z,34.6

`REACTIVITY_MONITOR`

A score of how reactive the user is to stressors.

Granularity: 1 minute

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/REACTIVITY_MONITOR?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "timestamp": ["2024-04-01T12:00:00Z", "2024-04-01T12:01:00Z"],
        "value": [0.5, 0.6],
        "label": ["CALM", "CALM"]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/REACTIVITY_MONITOR?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

timestamp,value,label
2024-04-01T12:00:00Z,0.5,CALM
2024-04-01T12:01:00Z,0.6,CALM

`SKIN_CONDUCTANCE_LEVEL`

Continuous skin conductance, measured in microSiemens (µS).

Granularity: 5 seconds

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/SKIN_CONDUCTANCE_LEVEL?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "timestamp": ["2024-04-01T12:00:00Z", "2024-04-01T12:00:05Z"],
        "value": [0.1, 0.12]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/SKIN_CONDUCTANCE_LEVEL?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

timestamp,value
2024-04-01T12:00:00Z,0.1
2024-04-01T12:00:05Z,0.12

`MOTION`

A score of how much the user has moved in the last minute.

Granularity: 1 minute

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/MOTION?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "timestamp": ["2024-04-01T12:00:00Z", "2024-04-01T12:01:00Z"],
        "value": [10, 20]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/MOTION?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

timestamp,value
2024-04-01T12:00:00Z,10
2024-04-01T12:01:00Z,20

For more information

See the Biometrics documentation for more details on these metrics.