| get_workouts | Get details about the workouts that the user has done during a period of time.
Result timestamps will include time zones. Always translate timestamps to the user's local
time zone when this is known. Args:
start_time: The starting time of the period. Must include tz (ISO8601).
end_time: the ending time of the period. Must include tz (ISO8601). |
| get_metrics_catalog | Get the catalog of available metrics that can be used in time-series API calls
(metric_time_series and metric_samples).
|
| get_metric_time_series | Get user's time-series data for a single Fulcra metric. Covers the time starting at start_time (inclusive) until end_time (exclusive).
Result timestamps will include tz. Always translate timestamps to the user's local
tz when this is known.
Args:
metric_name: The name of the time-series metric to retrieve. Use `get_metrics_catalog` to find available metrics.
start_time: The starting time period (inclusive). Must include tz (ISO8601).
end_time: The ending time (exclusive). Must include tz (ISO8601).
sample_rate: Optional. The number of seconds per sample. Default is 60. Can be smaller than 1.
replace_nulls: Optional. When true, replace all NA with 0. Default is False.
calculations: Optional. A list of additional calculations to perform for each
time slice. Not supported on cumulative metrics. Options: "max", "min", "delta", "mean", "uniques", "allpoints", "rollingmean".
Returns:
A JSON string representing a list of data points for the metric.
For time ranges where data is missing, the values will be NA unless replace_nulls is true. |
| get_metric_samples | Retrieve the raw samples related to a given metric for the user during a specified period. In cases where samples cover ranges and not points in time, a sample will be returned
if any part of its range intersects with the requested range. For example, if start_time
is 14:00 and end_time is 15:00, a sample covering 13:30-14:30 will be included.
Result timestamps will include time zones. Always translate timestamps to the user's local
time zone when this is known.
Args:
metric_name: The name of the metric to retrieve samples for. Use `get_metrics_catalog` to find available metrics.
start_time: The start of the time range (inclusive), as an ISO 8601 string or datetime object.
end_time: The end of the time range (exclusive), as an ISO 8601 string or datetime object.
Returns:
A JSON string representing a list of raw samples for the metric. |
| get_sleep_cycles | Return sleep cycles summarized from sleep stages. Processes raw sleep data samples into sleep cycles by finding gaps in the
sleep sample data within a specified time interval.
Result timestamps will include time zones. Always translate timestamps to the user's local
time zone when this is known.
Args:
start_time: The starting timestamp (inclusive), as an ISO 8601 string or datetime object.
end_time: The ending timestamp (exclusive), as an ISO 8601 string or datetime object.
cycle_gap: Optional. Minimum time interval separating distinct cycles (e.g., "PT2H" for 2 hours).
Defaults to server-side default if not provided.
stages: Optional. Sleep stages to include. Defaults to all stages if not provided.
gap_stages: Optional. Sleep stages to consider as gaps in sleep cycles.
Defaults to server-side default if not provided.
clip_to_range: Optional. Whether to clip the data to the requested date range. Defaults to True.
Returns:
A JSON string representing a pandas DataFrame containing the sleep cycle data. |
| get_location_at_time | Gets the user's location at the given time. If no sample is available for the exact time, searches for the closest one up to
window_size seconds back.
Result timestamps will include time zones. Always translate timestamps to the user's local
time zone when this is known.
Args:
time: The point in time to get the user's location for. Must include tz (ISO8601).
window_size: Optional. The size (in seconds) to look back (and optionally forward) for samples. Defaults to 14400.
include_after: Optional. When true, a sample that occurs after the requested time may be returned if it is the closest one. Defaults to False.
Returns:
A JSON string representing the location data. |
| get_location_time_series | Retrieve a time series of locations that the user was at.
Result timestamps will include time zones. Always translate timestamps to the user's local tz when this is known. Args:
start_time: The start of the time range (inclusive), as an ISO 8601 string or datetime object.
end_time: The end of the range (exclusive), as an ISO 8601 string or datetime object.
change_meters: Optional. When specified, subsequent samples that are fewer than this many meters away will not be included.
sample_rate: Optional. The length (in seconds) of each sample. Default is 900.
reverse_geocode: Optional. When true, Fulcra will attempt to reverse geocode the locations and include the details in the results. Default is False.
Returns:
A JSON string representing a list of location data points. |
| get_user_info | Return general info about the Context by Fulcra user. Returns user references such as time zone, calendar ids, and other metadata. |