API

Purpose

Reference for api surface.

Module Index

class oura.client.OuraClient(client_id=None, client_secret=None, access_token=None, refresh_token=None, refresh_callback=None, personal_access_token=None)

Make requests to Oura’s API. Provide either oauth client and token information to make requests on behalf of users, or a personal access token to access your own data.

API_ENDPOINT = 'https://api.ouraring.com'
__init__(client_id=None, client_secret=None, access_token=None, refresh_token=None, refresh_callback=None, personal_access_token=None)
Parameters:
  • client_id (str) – The client id - identifies your application.
  • client_secret (str) – The client secret. Required for auto refresh.
  • access_token (str) – Access token.
  • refresh_token (str) – Use this to renew tokens when they expire
  • refresh_callback (callable) – Callback to handle token response
  • personal_access_token (str) – Token used for accessing personal data
activity_summary(start=None, end=None)

Get activity summary for the given date range. See https://cloud.ouraring.com/docs/activity

Parameters:
  • start (str) – Beginning of date range, YYYY-MM-DD
  • end (str, optional) – End of date range, or None if you want the current day.
bedtime_summary(start=None, end=None)

Get bedtime summary for the given date range. See https://cloud.ouraring.com/docs/bedtime

Parameters:
  • start (str) – Beginning of date range, YYYY-MM-DD
  • end (str, optional) – End of date range, or None if you want the current day.
readiness_summary(start=None, end=None)

Get readiness summary for the given date range. See https://cloud.ouraring.com/docs/readiness

Parameters:
  • start (str) – Beginning of date range, YYYY-MM-DD
  • end (str, optional) – End of date range, or None if you want the current day.
sleep_summary(start=None, end=None)

Get sleep summary for the given date range. See https://cloud.ouraring.com/docs/sleep

Parameters:
  • start (str) – Beginning of date range, YYYY-MM-DD
  • end (str, optional) – End of date range, or None if you want the current day.
user_info()

Returns information about the current user.

See https://cloud.ouraring.com/docs/personal-info

class oura.client_pandas.OuraClientDataFrame(client_id=None, client_secret=None, access_token=None, refresh_token=None, refresh_callback=None, personal_access_token=None)

Similiar to OuraClient, but data is returned instead as a pandas.DataFrame object. Each row will correspond to a single day of data, indexed by the date.

Methods that have a convert paramter will apply transformations to a set of columns by default. This can be overridden by passing in a specific set of columns to convert, or disabled entirely by passing convert=False

__init__(client_id=None, client_secret=None, access_token=None, refresh_token=None, refresh_callback=None, personal_access_token=None)
Parameters:
  • client_id (str) – The client id - identifies your application.
  • client_secret (str) – The client secret. Required for auto refresh.
  • access_token (str) – Access token.
  • refresh_token (str) – Use this to renew tokens when they expire
  • refresh_callback (callable) – Callback to handle token response
  • personal_access_token (str) – Token used for accessing personal data
activity_df(start=None, end=None, metrics=None, convert=True, convert_cols=None)

Create a dataframe from activity summary dict object.

Parameters:
  • start (string representation of a date i.e. '2020-10-31') – Beginning of date range
  • end (string representation of a date i.e. '2020-10-31') – End of date range, or None if you want the current day.
  • metrics (A list of strings, or a string) – Metrics to include in the df.
  • convert (bool) – Whether to convert datetime columns to pandas types
  • convert_cols (list) – If convert is True, a set of columns to convert, or None for the default. Currently supported column types include datetime.
bedtime_df(start=None, end=None, metrics=None)

Create a dataframe from bedtime summary

Parameters:
  • start (string representation of a date i.e. '2020-10-31') – Beginning of date range
  • end (string representation of a date i.e. '2020-10-31') – End of date range, or None if you want the current day.
  • metrics (A list of strings, or a string) – Metrics to include in the df.
combined_df_edited(start=None, end=None, metrics=None)

Combines sleep, activity, and summary into one DF Some cols are unit converted for easier use or readability.

If user specifies a metric that appears in all 3 summaries, i.e. ‘score’, then all 3 metrics will be returned.

Each summary’s column is prepended with the summary name. i.e. sleep summary ‘total’ metric will be re-named ‘SLEEP.total’

Parameters:
  • start (string representation of a date i.e. '2020-10-31') – Beginning of date range
  • end (string representation of a date i.e. '2020-10-31') – End of date range, or None if you want the current day.
  • metrics (A list of strings, or a string) – Metrics to include in the df.
readiness_df(start=None, end=None, metrics=None)

Create a dataframe from ready summary dict object.

Parameters:
  • start (string representation of a date i.e. '2020-10-31') – Beginning of date range
  • end (string representation of a date i.e. '2020-10-31') – End of date range, or None if you want the current day.
  • metrics (A list of strings, or a string) – Metrics to include in the df.
sleep_df(start=None, end=None, metrics=None, convert=True, convert_cols=None)

Create a dataframe from sleep summary dict object.

Parameters:
  • start (string representation of a date i.e. '2020-10-31') – Beginning of date range
  • end (string representation of a date i.e. '2020-10-31') – End of date range, or None if you want the current day.
  • metrics (A list of strings, or a string) – Metrics to include in the df.
  • convert (bool) – Whether to convert datetime columns to pandas types
  • convert_cols (list) – If convert is True, a set of columns to convert, or None for the default. Currently supported column types include datetime, timespan, and hypnogram
user_info_df()
oura.client_pandas.to_pandas(summary, metrics=None, date_key='summary_date')

Creates a dataframe from a summary object

Parameters:
  • summary (list of dictionaries. See https://cloud.ouraring.com/docs/readiness for an example) – A summary object returned from API
  • metrics (A list of metric names, or alternatively a string for one metric name) – The metrics to include in the DF. None includes all metrics
  • date_key (str) – Column to set as the index