05 · API

REST API で数値を読み取る

1 つのサイトのダッシュボードの数値を、読み取り専用のキーで JSON として取得します。

01キー

キーはサイトの Setup ページの API keys で作成します。キー（opa_ と 40 文字）が表示されるのは 1 回だけです。保存されるのは、そのハッシュと先頭の数文字だけです。
キーが読み取れるのは、作成したサイト 1 つだけです。無効化はすぐに反映されます。
キーは読み取り専用です。ただし、作成時に Record payments にチェックを入れた場合は、決済の送信もできます（Payments API）。

すべてのリクエストで、キーを Authorization: Bearer opa_… として送ります。

Shell

export TALLY_API_KEY=opa_…
curl -s -H "Authorization: Bearer $TALLY_API_KEY" "https://tallybyoutpost.com/api/v1/sites"

02ルート

すべて https://tallybyoutpost.com/api/v1 配下の GET で、{id} はサイトの ID です。どのルートもダッシュボードと同じパラメーターを受け取り、ダッシュボードと同じ数値を返します。

ルート	返す内容
`GET /sites`	キーのサイト：ID、名前、ドメイン、タイムゾーン、モード。
`GET /sites/{id}/overview`	期間とその前の期間のダッシュボードの数値：訪問者、ページビュー、訪問、エンゲージメント時間、収益。
`GET /sites/{id}/timeseries`	グラフ：1 時間ごとまたは 1 日ごとの訪問者とページビュー。決済がある場合は収益も含みます。
`GET /sites/{id}/breakdown/{dimension}`	流入元、チャネル、ページ、国、デバイスなど。各行の収益も含みます。
`GET /sites/{id}/sales`	決済の一覧（新しい順）。それぞれの紐づけ方法も含みます。
`GET /sites/{id}/receipts/{payment_id}`	1 件の決済のレシート：初回訪問から決済までのつながり。
`GET /sites/{id}/coverage`	訪問者に紐づいた売上の割合（紐づけ方法別）と、修正。
`GET /sites/{id}/visitors`	訪問者の一覧。各訪問者の訪問と支払額も含みます。
`GET /sites/{id}/visitors/{visitor}`	1 人の訪問者の行動の流れ。
`GET /sites/{id}/goals`	達成された各ゴールと、コンバージョンした訪問者およびその収益、そしてファネル。
`GET /sites/{id}/funnels/{id}`	1 つのファネルを、ステップごとに。
`GET /sites/{id}/realtime`	直近 5 分間にサイトにいる人と、直近 1 時間の売上。
`GET /sites/{id}/peak-hours`	曜日別・現地時間の時間帯別の訪問、売上、収益。
`GET /sites/{id}/pages`	ページの読まれ方：閲覧数、閲覧時間、スクロール深度、入口と出口。
`GET /sites/{id}/path-to-purchase`	購入者がたどった経路：支払いまでの時間と訪問回数、ファーストタッチから帰属先の流入元まで。
`GET /sites/{id}/ltv`	各顧客を最初に連れてきた流入元別の顧客生涯価値。

収益順の流入元（過去 30 日間）

curl -s -H "Authorization: Bearer $TALLY_API_KEY" \
  "https://tallybyoutpost.com/api/v1/sites/k3xq2mfa7twp/breakdown/source?period=30d&sort=revenue"

03パラメーター

パラメーター	値
`period`	`today`、`yesterday`、`7d`、`30d`、`12m`。ルートごとにデフォルトがあります。
`from`, `to`	カスタム期間。`YYYY-MM-DD` で開始と終了の両方を指定し、最大 366 日です。`period` とは併用できません。
`compare`	`off`（デフォルト）、`previous`、`year` のいずれか。
`f.<dim>`	フィルター：`f.country=DE`、`f.source=x.com`、`f.page=/pricing`、`f.device=mobile` のほか、ダッシュボードのほかのディメンションも使えます。
`limit`, `cursor`	1 ページあたりの行数と、前のページの `next_cursor`。

ルートが受け付けないパラメーターは 400 で拒否されるため、タイプミスが正しい応答として通ることはありません。

04レスポンス

JSON 形式で、金額は整数のセントと通貨で表します：{"cents": 4900, "currency": "USD", "exponent": 2}。合計は米ドルで、各売上には請求時の金額も含まれます。
時刻は UTC の RFC 3339 形式です。日の区切りはサイトのタイムゾーンに従い、そのタイムゾーンはすべての range に示されます。
割合と率は 0 から 1 の値です。0.1234 は 12.34% を表します。
エラーは {"error": {"code", "message"}} の形で返り、message はそのまま表示できる一文です：400 invalid_parameter、401 unauthorized、402 payment_required（アカウントにプランがない）、404 not_found、429 rate_limited、503 unavailable。

05レート制限

キーごとに、REST と MCP をあわせて 1 分あたり 120 回までリクエストでき、使った分は順次回復します。すべてのレスポンスに X-RateLimit-Limit と X-RateLimit-Remaining が付き、上限を超えると、秒数を示す Retry-After とともに 429 が返ります。

06うまくいったか確認する

足りない情報や、実際の画面と違う点はありませんか？どのページかを添えて support@tallybyoutpost.com までお知らせください。