[OURA APIシリーズ_2] Pythonを使ったOURA APIデータへのアクセス

概要

本稿では、OURA ringにより生成されたデータに、プログラム言語Pythonを使ってアクセスする方法を紹介します。実際の順序としては、① Pythonや実行環境として使用するAnacondaのインストール、② 使用するライブラリのインストール、そして③ JupyterLabを使ったコードの実行です。OURA ringユーザでOURA APIを知らない方、あるいは未だOURA APIを使用するためのPersonal Access Tokens(PATs)を作成していない方は[OURA APIシリーズ_1] を参照にしてPATsを作成してください。プログラム言語に親しくない方でも本稿までの内容を実行することで、少なくともOURA ringによって生成された睡眠のデータを抽出できるようにまとめました。次回以降の記事で取得可能な全てのデータを取得できるようなコード一覧表を投稿する予定ですので、本稿を参考に、まずは睡眠データを抽出してみてください。それでは、以下の手順に従って、OURA ringの未抽出データへアクセスするためのPC環境を構築していきましょう。

Pythonのインストール

Pythonは、1991年にオランダ人プログラマーのグイド・ヴァン・ロッサムによって開発されたプログラム言語です。通常、Pythonでプログラミングを実行するときには「ライブラリ」という「ある目的に沿って関数や機能をまとめたパッケージ」を使用します。OURA APIから生成データをダウンロードするために、まずは、標準ライブラリを搭載した最新のPythonと、追加で必要になるライブラリをインストールします。PythonはMacOSに標準で付属しているターミナル(Terminal)を使って実行可能ですが、私は、実行したコードの記録や、実行経過の自動保存、出力データの保存・管理等が容易といった面で優れているJupyterLabという実行環境(対話型開発環境)を使用しています。Anacondaというパッケージ管理ソフトウェアをインストールすることでJupyterLabを実行できますので、こちらも併せてインストールしていきます。

Python.org から「Python」をインストールする

標準ライブラリを搭載した最新のPythonをPCにインストールします。ブラウザからpython.orgを検索します。トップページの「Downloads」プルダウンから使用しているPCのOSをクリックします。


クリックすると最新Verが「Latest Python」として確認できます。例えば2023年10月10日現在は「Latest Pythn 3 Release - Python 3.12.0」と記載してあり、最新VerがPython 3.12.0であることがわかります。下記の「Stable Releases」より、最新のinstallerをダウンロードしてPCへのインストールを実行します。

インストールを実行します。

インストールが完了すると、ローカルフォルダにPythonが保存されます。これでPythonのインストールは完了です。

Anacondaのインストール

次に、Pythonを実行する環境としてAnacondaをインストールします。こちらもブラウザでanaconda.comを検索し、ダウンロードを進めていきます。トップページの「Free Download」をクリックします。

「Download」をクリックして進みます。

インストーラーが表示されますので、ローカルフォルダを指定してインストールを完了してください。完了すると、AnacondaのAppがLaunchpad内に表示されます。クリックしてAppを立ち上げます。

インターネット接続下で「JupyterLab」を起動させると、JupyterLab内のLauncherが表示されます。Python3のボタンをクリックすれば、前項でインストールしたPython3をJypyterLabのNotebookで実行することができます。

ライブラリのインストール

ここからは実際にJupyterLab上でPythonコマンドを実行してデータを抽出していきます。OURA APIから抽出するデータは、.json(JavaScript Object Notation)形式で出力されます。一方、プログラマーではない私たちにとって、この形式のデータは非常に扱いづらいです。例えば、私の睡眠データを抽出した画面を示します。

整然としていますが、１行で示されたこのようなデータを処理するのは大変そうですよね、、、。一方、いくつかのライブラリを追加してコードを実行すると.csvなど、扱い易い形式のデータを出力することができます。
Pythonのパッケージ管理システム「pip」を使うとライブラリをインストールしたり、アップデートしたりすることができます。
まずは、ライブラリ「oura」と、PATsを使ってデータを抽出するためのライブラリ「requests」をインストールします。下記のコマンドをNotebookに入力し、Shift＋Enterで実行してください。2つのライブラリがインストールされるはずです。

# oura libraly
!pip install oura
# requests
!pip install requests

これでひとまず準備完了です。下記で認証方法と使用するAPIのバージョンを説明したのちに、データの抽出を行なっていきます。

認証方法とAPI version

公式Webでは、PATsを使って2つの方法によりデータにアクセスすることができると紹介してあります。URL parameterは[OURA APIシリーズ_1] で実行した通り、URLにPATsを付与してブラウザで検索する方法です。今後は、方法1.に示されたHTTP headerという認証方法によりAPIにアクセスしていきます。

OURA API V1は2016年に、V2は2022年にリリースされています。本稿を読んでからPATsを作成する場合、そしてGen3以降のOura ringをお持ちの場合は、V1とV2の両方のデータにアクセスできます。V2の方が豊富なデータが出力できますし、日中・睡眠時の全ての時間でHRが取得可能なことを確かめました。そこで、本稿ではV2データへのアクセスを示します。

睡眠時の心拍数と心拍変動データを抽出し.csvで出力する

例として、睡眠時の2つのデータ「心拍数と心拍変動」について、API V2よりデータを抽出していきます。コードはこちらです。

#ライブラリをimportします
import requests
import json
import pandas as pd

url = 'https://api.ouraring.com/v2/usercollection/sleep'

#日付を任意に指定してください
params={
    'start_date': '2023-XX-XX',
    'end_date': '2023-XX-XX'
}

#自分のPATsを置換してください
headers = {
  'Authorization': 'Bearer <自分のPATsを入力>'
}
response = requests.request('GET', url, headers=headers, params=params)
print(response.text)

#.csvの保存名を任意で入力してください
response_json = json.loads(response.text)
hr_list = response_json["data"][0]["heart_rate"]["items"]
hr_dict = {"heart_rate": hr_list}
df =pd.DataFrame(hr_dict)
df.to_csv('hr23XXXX.csv')

hrv_list = response_json["data"][0]["hrv"]["items"]
hrv_dict = {"hrv": hrv_list}
df = pd.DataFrame(hrv_dict)
df.to_csv('hrv23XXXX.csv')

実際に返ってくる画面はこちらです。また、ローカルフォルダには、心拍数(heart_rate)と心拍変動(hrv)の.csvファイルが出力されているはずです。以下で、使用するライブラリやコードの意味について少しだけ説明します。

今回使用(import)するライブラリは、requests / json / pandasの3つです。それぞれ、HTTPリクエストを送信するため、JSON形式のデータを操作するため、そしてデータフレームとしてデータを操作するために必要なライブラリです。url=の尾部をreadiness / sleep / activity / bedtimeと変更することで、それぞれのV2データにアクセスできます。日付の指定はparamsにて行います。bearer認証にPATsを用いることでAPIへのアクセスが承認されます。あとはリストとして「どのデータを抽出するか」を指定したり、ディクショナリーとしてキー(変数の種類)と値(変数の値)を定義して.csvに出力するコードになります。

まとめ

本稿ではOURA APIの認証トークンPATsを使用してAPIデータにアクセスし、データを抽出、出力する方法を紹介しました。具体的には、Python / Anacondaのインストール、ライブラリのインストール、コードの実行です。それぞれのデータを抽出するコードはAPI Documentationに丁寧に記してあります。抽出したいデータがあるときは、こちらのWebページから「Python」のコード参照にJupyterLabで実行してみてください。

次回以降もデータ抽出のためのコードについて、また、なるべく早く「OURA APIコード一覧」のようなチート記事を投稿したいと思っています。それではまた！