機能

エージェントの報告

エージェントやアプリは、ユーザーが今体験した待ち時間を報告できます。報告はライブの掲示待ち時間がない場所を補い、常に報告であると表示され、ER と urgent care では受け付けません。

概要

POST /v1/places/{id}/reports と report_wait ツールは、誰かが実際に体験した待ち時間を保存します。報告は掲示された待ち時間とは分けて扱われ、独自の階層 agent を持ち、公式や場所が掲示した数値と混ぜることはありません。

報告のしかた

来訪の直後に、ユーザーが待った分数を送ってください。報告には API キーが必要で、1 回の呼び出しとして数えます。

wait_min：分。0〜600。必須。
observed_at：ユーザーが待った時刻。オフセット付きの ISO 8601 で、過去 2 時間以内。既定は現在。
kind：まだ列に並んでいる間は in_line（ここまでの待ち時間）、待ち終えた直後の全体の待ち時間は done。

curl -X POST "https://api.waity.ai/v1/places/pl_nvk0wkb3ps/reports" \
  -H "X-Api-Key: $WAITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wait_min":25,"kind":"done"}'

保存された報告は 201 で、report.id と shown を返します。表示されないときは reason が理由を示します：needs_more_reports、official_wait、closed、too_old、out_of_range。

MCP ツール

report_wait は同じフィールドに加えて場所の id を受け取ります。書き込む唯一の MCP ツールなので、アノテーションは読み取り専用ではないことを示します。

報告が表示されるとき

場所に使える公式または場所掲示の待ち時間がなく、閉まっていないときだけです。ライブの掲示待ち時間が常に優先され、報告は履歴に残ります。
過去 45 分以内に 2 人以上の異なる人が報告または確認したとき、または信頼できる報告者(以前の報告が他の人に確認された人)が報告したときだけです。
表示される待ち時間は、各人の最新の報告の中央値です。期間内の人が 2 人未満になると表示されなくなります。

表示のしかた

報告された待ち時間は now.tier: "agent"、now.basis: "reported"、now.source.name: "people" を持ち、独自の now.source.short が付きます。概要には、人々が報告したこと（「reported by 2 people」）、場所が掲示したものではないことが書かれます。

報告された分数は掲示された分数と比べません。両方を含むリストはその旨を示し、instead が一方を他方より短いとして提示することはありません。

ER と urgent care には使えません

そこへの報告は 422 reports_not_accepted で拒否され、何も保存されません。

制限とプライバシー

キーなしの呼び出しは 401 key_required になり、カウントされません。
報告者ごと、場所ごとに 30 分に 1 件（429 report_too_soon、Retry-After 付き）。
報告者ごとに 1 日 200 件（429 report_limit、UTC の午前 0 時まで）。
報告と一緒に保存されるのはキーの ID だけです。名前、電話番号などの個人データは送らないでください。

1 つのキーで多くの人の報告を送る SMS サービスのような報告パートナーは、reporter を送れます。各人の安定した一方向ハッシュで、電話番号やメールアドレスそのものは決して送りません。パートナーキーは Waity が設定します。それ以外のキーの reporter は無視されます。

履歴

報告は tier=agent で履歴に入ります。raw では報告ごとに、時間別・日別の値は掲示された待ち時間と同じ方法で作られます。