ベビートラッカーAPI：自分のコードから睡眠や授乳を記録する

ミルクはちょうどいい温度で、赤ちゃんはやっと肩の上で落ち着きました。記録アプリの入ったスマートフォンは、お決まりのように隣の部屋で充電中です。一方、廊下の収納ではRaspberry Piが静かに動いていて、頭の片隅の頑固な自分がもう考えはじめています。POSTリクエストを1本送れば済むのでは、と。

実際、それで済みます。nappiは公開のREST APIを用意していて、nappi Premiumを利用している家族なら誰でも、自分たちのデータに使えます。個人用のキーを作ってリクエストごとに送るだけで、スクリプトからおむつ、ミルク、授乳、搾乳、睡眠、アクティビティ、成長を記録したり、タイマーを開始・停止したり、最新の記録を読み取ったりできます。仕様書の全体は https://api.nappi.app/v1/openapi.json で公開しています。

nappiにAPIはありますか？

あります。ベースURLは https://api.nappi.app/v1 で、どの呼び出しも普通のHTTPS、送るのも受け取るのもJSONです。

APIはOpenAPI 3.1のドキュメントで記述されています。OpenAPIは、HTTP APIを記述するための標準的でプログラミング言語に依存しない形式です。¹ 仕様書をコードジェネレーターやPostmanに読み込ませれば、フィールド名を推測しなくても動くクライアントが手に入ります。

JSONを読むよりクリックで確かめたい場合は、インタラクティブなAPIリファレンス（英語）で、すべてのエンドポイントを例つきで確認できます。読むだけならアカウントは不要です。サインインすると、リクエストを試せるパネルに自分のキーの一覧が表示され、そのページから実際のリクエストを送れるようになります。

APIはまだベータ版なので、ご家族の使い方を見ながら、リクエストの形式が変わることがあります。リファレンスは稼働中のAPIから生成されているので、常に公開中の内容と一致しています。

nappiのAPIキーはどうやって手に入れますか？

キーはアプリではなくWebで作ります。

1. nappi.app/app/connections（英語）にサインインします。できればパソコンからがおすすめです。
2. 「子ども部屋のPi」「キッチンのダッシュボード」など、あとで見分けがつく名前をキーに付け、有効期間を30日、90日、1年から選びます。
3. キーをコピーします。キーは nappi_ で始まり、表示されるのは一度だけです。

キーはリクエストごとに Authorization ヘッダーで Bearer nappi_YOUR_KEY という形で送ります。これはRFC 6750で定められたベアラートークンの形式です。² ベアラートークンは持っている人なら誰でも使えるので、パスワードと同じように扱ってください。

何かを作りはじめる前に、知っておきたいルールがいくつかあります。

• APIはnappi Premiumに含まれています。1つのサブスクリプションで家族全員が使え、家族がPremiumでない間はキーが使えなくなります。
• キーを作れるのはお世話をする人（ケアギバー）だけです。閲覧者やゲストは作れません。
• 同時に持てるキーは10個までです。
• 使っているキーの期限が切れる1週間前に、メールでお知らせします。

nappiのAPIでできること

エンドポイントは8つで、どれも自分の家族の赤ちゃんに限られます。

メソッド	パス	できること
GET	/v1/babies	赤ちゃんの一覧とIDを取得
GET	/v1/babies/{babyId}/entries/latest	種類ごとの最新の記録
GET	/v1/babies/{babyId}/entries/latest/{type}	1種類の最新の記録
POST	/v1/babies/{babyId}/entries	終わった出来事を記録
GET	/v1/babies/{babyId}/timers	動いている睡眠・授乳・搾乳タイマー
GET	/v1/babies/{babyId}/status	タイマーと最新の記録を1回で取得
POST	/v1/babies/{babyId}/timers/{timerType}/start	タイマーを開始
POST	/v1/babies/{babyId}/timers/{timerType}/stop	タイマーを止めて記録を保存

できないことも知っておきましょう。薬と離乳食はまだ記録できませんが、それぞれの最新の記録を読むことはできます。また、APIが返すのは種類ごとの最新の記録だけで、履歴の全体ではありません。記録を編集したり削除したりする方法もありません。

curl で最初の記録をつける

まずは赤ちゃんのIDを調べます。

curl https://api.nappi.app/v1/babies \
  -H "Authorization: Bearer nappi_YOUR_KEY"

配列が返ってきます。

[
  {
    "id": "BABY_ID",
    "name": "Phoebe",
    "birth_date": "2026-05-02",
    "timezone": "America/New_York"
  }
]

次に、おしっこのおむつを記録します。

curl -X POST https://api.nappi.app/v1/babies/BABY_ID/entries \
  -H "Authorization: Bearer nappi_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type": "diaper", "diaper_type": "wet"}'

201 が返れば記録完了で、レスポンスの本文に作成された内容が入っています。

{ "id": "ENTRY_ID", "type": "diaper", "duplicate": false }

Idempotency-Key ヘッダーは任意です。それでも、自動化で省くことはおすすめしません。接続が切れてスクリプトが同じ Idempotency-Key で再試行しても、2回目のリクエストは "duplicate": true つきの 200 を返し、新しい記録は書き込まれません。おむつが2枚になることはありません。

APIからの記録は、nappiの普通の記録と同じです。家族全員がアプリで見られて、キーを作った人、つまりあなたの記録として扱われます。

時刻はUTCからのオフセットつきのISO 8601形式（例：2026-10-21T14:30:00-04:00）で、省略すると現在時刻になります。量の単位はミリリットルで、"unit": "oz" を送った場合はオンスになります。

記録できる種類

POST /entries には type と、その種類に必要なフィールドを送ります。

type	必須	任意
diaper	diaper_type：wet、poo、mixed、dry のいずれか	time
potty	outcome：potty、accident、sat_dry のいずれか	time
bottle	なし	amount、unit（ml または oz）、bottle_type（breast_milk、formula など）、time
nursing	なし	side、left_minutes、right_minutes、duration_minutes、time
pumping	なし	amount、left_amount、right_amount、unit、duration_minutes、time
sleep	start_time、end_time	sleep_type（nap または night）
activity	activity_type（bath、tummy_time など）	duration_minutes、time
growth	なし	weight、weight_unit（kg または lb）、length、head、length_unit（cm または in）、time

粉ミルクを4オンス飲んだときは、こう書きます。

{ "type": "bottle", "amount": 4, "unit": "oz", "bottle_type": "formula" }

sleep_type を省くと、nappiが赤ちゃんの日中の時間帯をもとに、お昼寝か夜の睡眠かをアプリと同じ方法で判断します。お昼寝の途中など、まだ続いている出来事にはタイマーを使ってください。

スクリプトから睡眠タイマーを開始・停止する

タイマーは、家族全員がアプリで見ている共有のタイマーそのものです。お昼寝を開始するには、こうします。

curl -X POST https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/start \
  -H "Authorization: Bearer nappi_YOUR_KEY"

停止すると、スマートフォンで止めたときとまったく同じように睡眠の記録が保存されます。

curl -X POST https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/stop \
  -H "Authorization: Bearer nappi_YOUR_KEY"

timerType には sleep、nursing、pumping を指定できます。すでに動いているタイマーを開始しても何も変わらず、"status": "already_running" つきでそのタイマーが返ってきます。何も動いていないときに停止すると、コード timer_not_running つきの 409 が返るので、1つのボタンでオン・オフを切り替える仕組みも簡単に作れます。

連携は双方向です。GET /timers は、誰かがスマートフォンやウォッチ、Alexaで開始したタイマーも返します。授乳タイマーには任意で side を指定でき、start_time を使えば開始時刻を最大48時間さかのぼれます。

小さなスクリプト：最後に飲んでからの経過時間

このNodeのスクリプト（Node 18以降、パッケージ不要）は、ミルクと授乳の両方を見て、最後に飲んでからどれくらいたったかを表示します。last-feed.mjs という名前で保存して、node last-feed.mjs で実行してください。

const KEY = "nappi_YOUR_KEY";
const BABY = "BABY_ID";

const res = await fetch(
  `https://api.nappi.app/v1/babies/${BABY}/status?types=bottle,nursing`,
  { headers: { Authorization: `Bearer ${KEY}` } },
);
if (!res.ok) throw new Error(`nappi returned ${res.status}`);
const { timers, latest } = await res.json();

const feeds = [latest.bottle, latest.nursing].filter(Boolean);
if (timers.some((t) => t.type === "nursing")) {
  console.log("Nursing right now");
} else if (feeds.length === 0) {
  console.log("No feeds logged yet");
} else {
  const last = Math.max(...feeds.map((f) => new Date(f.time).getTime()));
  const min = Math.round((Date.now() - last) / 60000);
  console.log(`Last feed ${Math.floor(min / 60)}h ${min % 60}m ago`);
}

cron と冷蔵庫に貼った電子ペーパーの画面につなげば、夜中の3時に最後のミルクがいつだったかを調べるために、誰もスマートフォンのロックを解除しなくて済みます。

レート制限に引っかからないポーリングのしかた

キーごとに、読み取りは1分あたり12回、書き込みは30回までです。超えると 429 Too Many Requests が返り、何秒待てばよいかを Retry-After ヘッダーが教えてくれます。³⁴

ダッシュボードで使う場合、/status へのポーリングは1分に1回までにしてください。レスポンスには ETag がついています。これを If-None-Match で送り返せば、何かが変わるまでは本文なしの 304 Not Modified が返ります。⁴

例外が1つあります。タイマーが動いている間は経過時間が毎秒変わるので、/status は常に完全な 200 を返します。

iPhoneのショートカット：ワンタップでミルクを記録

これはパソコンなしでできます。ショートカットAppで 「URLの内容を取得」 アクションを追加し、次のように設定します。

• URL：https://api.nappi.app/v1/babies/BABY_ID/entries
• 方法：POST
• ヘッダ：Authorization に Bearer nappi_YOUR_KEY
• 本文を要求：JSON。type を bottle、amount を 120（数値として）、unit を ml に設定

方法をPOSTに切り替えると「本文を要求」の項目が現れ、その選択肢の1つがJSONです。⁵ ショートカットをホーム画面に置くか、前に「入力を要求」のステップを足して、毎回量を入力できるようにしてもいいでしょう。

音声での記録なら、nappiアプリがすでにSiriに対応しています。この方法が向いているのは、「粉ミルク120 ml」をワンタップで記録するボタンや、哺乳瓶の水切りラックに貼ったNFCタグにスマートフォンをかざすと動くオートメーションのような、自分好みの使い方です。

Home Assistant：インテグレーションか、シンプルなRESTコマンドか

家のことをHome Assistantで動かしているなら、まずはインテグレーションから始めてください。MITライセンスのオープンソースとしてGitHubのnappi-app/nappi-home-assistant（英語）で公開しており、HACSのデフォルトストアで「nappi」と検索すれば見つかります。赤ちゃん1人につき2分に1回 /status を確認し、記録ボタン、タイマーのスイッチ、最新の記録のセンサーを、YAMLに触れずに使えるようにしてくれます。インストールの手順と、まねしたいオートメーションの例は、Home Assistant連携ガイド（英語）で紹介しています。

YAMLのほうが好きなら、Home AssistantのRESTful Commandインテグレーションで、独自のヘッダーとJSONの本文を付けてAPIを直接呼び出せます。⁶ 次の2つのコマンドで、お昼寝を開始・停止できます。

# secrets.yaml
nappi_auth: "Bearer nappi_YOUR_KEY"

# configuration.yaml
rest_command:
  nappi_sleep_start:
    url: "https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/start"
    method: post
    headers:
      Authorization: !secret nappi_auth
  nappi_sleep_stop:
    url: "https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/stop"
    method: post
    headers:
      Authorization: !secret nappi_auth

ベビーベッドの横のボタンから rest_command.nappi_sleep_start を呼び出せば、家族全員のスマートフォンでお昼寝タイマーが動きだします。AlexaやGoogle Homeなど、ほかの連携方法はスマートホームのページ（英語）にまとめています。

スクリプトに赤ちゃんのデータへのアクセスを渡しても安全ですか？

キーを作らない限り、APIを通して家族のデータを読めるものは何もありません。キーはそれぞれ1つの家族の1人のケアギバーに属し、nappiが保存するのはキーのSHA-256ハッシュだけです。キーが一度しか表示されないのはそのためです。

キーはいつでもnappi.app/app/connections（英語）、またはアプリの Settings → Connections → Smart home から取り消せます。期限が切れたとき、あなたが家族から抜けたとき、閲覧者になったときにも、キーは使えなくなります。

キーでできるのは、アプリであなたがするのと同じ記録と読み取りで、タイマーの操作も含まれます。アカウントを変更したり、パスワードを見たりすることはできません。公開のGitリポジトリやスクリーンショットには載せないようにし、漏れたらすぐに取り消してください。

今夜さっそく試してみてください。30日のキーを作り、/babies の curl を実行して、テスト用のおむつを1件記録します。パートナーのスマートフォンに表示されたら、そこで削除してください。APIでは削除できないからです。

よくある質問

nappiのAPIに追加料金はかかりますか？

別料金はかかりませんが、APIはnappi Premiumに含まれる機能です。1つのサブスクリプションで家族全員が使えます。ドキュメントとOpenAPIの仕様書は、誰でも無料で読めます。

APIで履歴をすべてエクスポートできますか？

できません。APIが返すのは種類ごとの最新の記録と、動いているタイマーです。履歴をすべて取り出したいときは、nappiアプリのCSVエクスポートを使ってください。

双子やきょうだいでも使えますか？

使えます。GET /v1/babies は家族の赤ちゃん全員を返し、ほかの呼び出しではIDで赤ちゃんを1人指定します。スクリプトは赤ちゃん1人につき1回実行してください。

APIで薬を記録できますか？

まだできません。薬の最新の記録を読むことはできますが、薬や離乳食の記録には対応していないので、これらは引き続きアプリで記録してください。