API リファレンス

Stratum α REST API を使って、エリア分析・シミュレーション・ペルソナデータをプログラムから利用できます。

認証

すべてのリクエストに Authorization: Bearer sk_... ヘッダーが必要です。 APIキーはダッシュボードのAPI設定から作成できます。

curl -H "Authorization: Bearer sk_your_api_key_here" \
  https://stratum.oku-ai.co.jp/api/v1/areas/13101

レート制限

APIキーごとに60リクエスト/分の制限があります。制限を超えると 429 Too Many Requests を返します。レスポンスヘッダーで残り回数を確認できます。

ヘッダー	説明
X-RateLimit-Limit	ウィンドウ内の上限数
X-RateLimit-Remaining	残りリクエスト数
X-RateLimit-Reset	リセットまでの秒数

ベースURL

https://stratum.oku-ai.co.jp

エンドポイント

GET/api/v1/areas/{areaCode}

指定したエリアコード（5桁JISコード）のプロファイルデータを取得します。人口・経済・リスク情報を含みます。

パラメータ

名前	型	必須	説明
areaCode	string	はい	5桁の市区町村JISコード（例: 13101 = 千代田区）

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  https://stratum.oku-ai.co.jp/api/v1/areas/13101

レスポンス例

{
  "areaCode": "13101",
  "areaName": "東京都千代田区",
  "population": 67927,
  "households": 38516,
  "agingRate": 0.186,
  "avgIncome": 711,
  "stationCount": 21,
  "compositeHazard": 0.32
}

GET/api/v1/areas/{areaCode}/scores

エリアのスコアインデックス（総合スコア・各カテゴリスコア）を取得します。

パラメータ

名前	型	必須	説明
areaCode	string	はい	5桁の市区町村JISコード

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  https://stratum.oku-ai.co.jp/api/v1/areas/13101/scores

レスポンス例

{
  "areaCode": "13101",
  "overallScore": 82.5,
  "categories": {
    "people": 78,
    "economy": 91,
    "business": 85,
    "risk": 76
  }
}

GET/api/v1/areas/ranking

エリアを指定カテゴリでランキングします。都道府県フィルタ対応。

パラメータ

名前	型	必須	説明
category	string	はい	people / economy / business / risk
prefCode	string	-	都道府県コード（01-47）で絞り込み
limit	number	-	取得件数（デフォルト: 20、最大: 100）

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  "https://stratum.oku-ai.co.jp/api/v1/areas/ranking?category=economy&limit=10"

レスポンス例

{
  "category": "economy",
  "items": [
    { "areaCode": "13103", "areaName": "東京都港区", "score": 95.2, "rank": 1 },
    { "areaCode": "13101", "areaName": "東京都千代田区", "score": 91.8, "rank": 2 }
  ]
}

GET/api/v1/areas/compare

2つのエリアを比較します。全カテゴリのスコア差分を返します。

パラメータ

名前	型	必須	説明
a	string	はい	比較元エリアコード
b	string	はい	比較先エリアコード

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  "https://stratum.oku-ai.co.jp/api/v1/areas/compare?a=13101&b=27128"

レスポンス例

{
  "a": { "areaCode": "13101", "areaName": "東京都千代田区", "scores": { ... } },
  "b": { "areaCode": "27128", "areaName": "大阪府中央区", "scores": { ... } },
  "diff": { "people": 3.2, "economy": -1.5, "business": 5.8, "risk": -2.1 }
}

GET/api/v1/simulations

アカウントに紐づくシミュレーションの一覧を取得します。ステータス・テンプレート・サマリーを含みます。

パラメータ

名前	型	必須	説明
limit	number	-	取得件数（デフォルト: 50、最大: 100）
offset	number	-	オフセット（デフォルト: 0）

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  "https://stratum.oku-ai.co.jp/api/v1/simulations?limit=10"

レスポンス例

{
  "data": [
    {
      "id": "01J...",
      "templateType": "ad_test",
      "category": "test",
      "areaCode": "13101",
      "status": "completed",
      "resultSummary": { "overall_score": 72.5, ... },
      "createdAt": "2026-05-02T09:30:00Z",
      "completedAt": "2026-05-02T09:31:15Z"
    }
  ]
}

POST/api/v1/simulations

シミュレーションを作成・実行します。非同期処理のため、レスポンスのIDで GET /simulations/{id} をポーリングしてください。Max 5x以上のプラン限定。

パラメータ

名前	型	必須	説明
templateType	string	はい	テンプレートタイプ（ad_test, price_test, segment_discovery 等）
inputParams	object	はい	テンプレート固有の入力パラメータ
personaCount	number	はい	生成ペルソナ数（5〜5000）
areaCode	string	-	対象エリアコード（5桁JISコード）
workspaceId	string	-	ワークスペースID（省略時は最初の所属WS）

リクエスト例

curl -X POST -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"templateType":"ad_test","personaCount":100,"areaCode":"13101","inputParams":{"businessType":"restaurant","adCopy":"新メニュー登場"}}' \
  https://stratum.oku-ai.co.jp/api/v1/simulations

レスポンス例

{
  "data": { "id": "01J...", "status": "queued" }
}

GET/api/v1/simulations/{id}

シミュレーション結果を取得します。status が completed になるまでポーリングしてください。

パラメータ

名前	型	必須	説明
id	string	はい	シミュレーションID

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  https://stratum.oku-ai.co.jp/api/v1/simulations/01J...

レスポンス例

{
  "id": "01J...",
  "status": "completed",
  "templateType": "ad_test",
  "resultSummary": "...",
  "resultData": { ... },
  "completedAt": "2026-05-02T10:01:30Z"
}

GET/api/v1/personas

アカウントに紐づくペルソナの一覧を取得します。

パラメータ

名前	型	必須	説明
limit	number	-	取得件数（デフォルト: 50、最大: 100）
offset	number	-	オフセット（デフォルト: 0）

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  "https://stratum.oku-ai.co.jp/api/v1/personas?limit=20"

レスポンス例

{
  "data": [
    { "id": "01J...", "name": "田中太郎", "age": 35, "gender": "male", "occupation": "会社員", "areaCode": "13101", "growthLevel": 3 }
  ]
}

GET/api/v1/personas/{id}

ペルソナの詳細情報を取得します。

パラメータ

名前	型	必須	説明
id	string	はい	ペルソナID

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  https://stratum.oku-ai.co.jp/api/v1/personas/01J...

レスポンス例

{
  "data": {
    "id": "01J...",
    "name": "田中太郎",
    "age": 35,
    "occupation": "会社員",
    "areaCode": "13101",
    "traits": { ... },
    "decisionWeights": { ... }
  }
}

GET/api/v1/personas/{id}/psychology

ペルソナの心理プロファイル（Big Five・Schwartz価値観・心理指標）を取得します。Max 5x以上のプラン限定。

パラメータ

名前	型	必須	説明
id	string	はい	ペルソナID

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  https://stratum.oku-ai.co.jp/api/v1/personas/01J.../psychology

レスポンス例

{
  "data": {
    "openness": 0.72, "conscientiousness": 0.58, "extraversion": 0.44,
    "agreeableness": 0.81, "neuroticism": 0.35,
    "valSelfDirection": 0.68, "valSecurity": 0.52,
    "stressTolerance": 0.65, "financialAnxiety": 0.42
  }
}

GET/api/v1/segments

セグメント一覧を取得します。シミュレーションから自動生成されたセグメントを含みます。

パラメータ

名前	型	必須	説明
limit	number	-	取得件数（デフォルト: 50、最大: 100）
offset	number	-	オフセット（デフォルト: 0）

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  "https://stratum.oku-ai.co.jp/api/v1/segments?limit=20"

レスポンス例

{
  "data": [
    { "id": "01J...", "name": "健康志向ファミリー", "areaCode": "13101", "score": 85, "segmentData": { ... } }
  ]
}

GET/api/v1/segments/{id}

セグメントの詳細データ（デモグラフィクス・行動特性・心理特性）を取得します。

パラメータ

名前	型	必須	説明
id	string	はい	セグメントID

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  https://stratum.oku-ai.co.jp/api/v1/segments/01J...

レスポンス例

{
  "data": {
    "id": "01J...", "name": "健康志向ファミリー", "areaCode": "13101", "score": 85,
    "segmentData": { "demographics": { ... }, "behavior": { ... }, "sentiment": { ... } }
  }
}

GET/api/v1/observations

観測ジョブ一覧を取得します。APIアクセス自体は Max 5x以上のプランが必要です。アプリ内の観測機能提供条件は別途料金表に従います。

パラメータ

名前	型	必須	説明
limit	number	-	取得件数（デフォルト: 50、最大: 100）
offset	number	-	オフセット（デフォルト: 0）

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  "https://stratum.oku-ai.co.jp/api/v1/observations?limit=10"

レスポンス例

{
  "data": [
    { "id": "01J...", "observationType": "price_monitor", "title": "千代田区飲食店価格", "status": "active", "runCount": 12 }
  ]
}

GET/api/v1/observations/{id}

観測ジョブの詳細と直近20件の観測結果を取得します。APIアクセス自体は Max 5x以上のプランが必要です。アプリ内の観測機能提供条件は別途料金表に従います。

パラメータ

名前	型	必須	説明
id	string	はい	観測ジョブID

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  https://stratum.oku-ai.co.jp/api/v1/observations/01J...

レスポンス例

{
  "data": {
    "id": "01J...", "observationType": "price_monitor", "title": "千代田区飲食店価格",
    "status": "active", "runCount": 12, "monthlySpentYen": 360,
    "recentResults": [ { "id": "01J...", "status": "completed", "data": { ... } } ]
  }
}

POST/api/v1/areas/{areaCode}/generate

エリアプロファイルの生成をリクエストします。未分析エリアのデータ生成に使用します。

パラメータ

名前	型	必須	説明
areaCode	string	はい	5桁の市区町村JISコード

リクエスト例

curl -X POST -H "Authorization: Bearer sk_your_key" \
  https://stratum.oku-ai.co.jp/api/v1/areas/13101/generate

レスポンス例

{
  "status": "queued",
  "areaCode": "13101",
  "message": "Profile generation has been queued"
}

GET/api/v1/chains

チェーン（店舗グループ）の一覧を取得します。

パラメータ

名前	型	必須	説明
limit	number	-	取得件数（デフォルト: 50、最大: 100）
offset	number	-	オフセット（デフォルト: 0）

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  "https://stratum.oku-ai.co.jp/api/v1/chains?limit=10"

レスポンス例

{
  "data": [
    { "id": "01J...", "name": "カフェチェーンA", "storeCount": 12, "areaCode": "13101", "createdAt": "2026-04-15T08:00:00Z" }
  ]
}

GET/api/v1/chains/{id}

チェーンの詳細情報（店舗一覧・集計データ）を取得します。

パラメータ

名前	型	必須	説明
id	string	はい	チェーンID

リクエスト例

curl -H "Authorization: Bearer sk_your_key" \
  https://stratum.oku-ai.co.jp/api/v1/chains/01J...

レスポンス例

{
  "data": {
    "id": "01J...",
    "name": "カフェチェーンA",
    "storeCount": 12,
    "stores": [
      { "areaCode": "13101", "areaName": "東京都千代田区", "status": "active" }
    ]
  }
}

Trade Area API (B2B)

店舗・施設の商圏分析・競合調査・需要予測・候補地比較を外部システムから利用するためのAPIです。飲食・小売・美容・医療・フィットネス・教育・不動産の7業種に対応し、業種ごとに最適化されたスコアリングを提供します。

対応業種

industry パラメータで業種を指定すると、スコア重みと経済指標が業種に最適化されます。

industry	業種	重視スコア	活用例
restaurant	飲食店	需要 25%	居酒屋・カフェ・レストラン
retail	小売店	競合 25%	ドラッグストア・コンビニ・アパレル
service	サービス業	アクセス+経済各25%	美容室・ネイルサロン・エステ
clinic	医療機関	アクセス 30%	内科・歯科・皮膚科
fitness	フィットネス	アクセス 25%	ジム・ヨガスタジオ・ピラティス
education	教育	需要 30%	学習塾・英会話・プログラミング教室
real_estate	不動産	経済 30%	不動産仲介・賃貸管理

認証（B2B）

B2B APIでは stra_live_ または stra_test_ プレフィックスのキーを使用します。テストキーはモックデータを返します。ダッシュボードのAPI設定で「Trade Area API (B2B)」タブからキーペアを作成できます。

プラン	レート制限	月額
Starter	100 req/min	¥30,000/店舗
Growth	500 req/min	¥50,000/店舗
Enterprise	2,000 req/min	別途見積

B2Bエンドポイント

POST/api/v1/trade-area

指定した住所または座標の商圏分析レポートを生成します。人口・競合・需要・経済・アクセス・リスクの6軸で分析し、総合スコアを算出します。結果は7日間キャッシュされます。

パラメータ

名前	型	必須	説明
store_id	string	はい	店舗識別子
address	string	-	住所（addressまたはlat/lngが必要）
lat	number	-	緯度
lng	number	-	経度
radius_m	number	-	分析半径（100-3000m、デフォルト: 500）
industry	string	-	業種: restaurant / retail / service / clinic / fitness / education / real_estate
sub_industry	string	-	サブ業種

リクエスト例

curl -X POST -H "Authorization: Bearer stra_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"store_001","address":"東京都渋谷区神南1-2-3","industry":"restaurant"}' \
  https://stratum.oku-ai.co.jp/api/v1/trade-area

レスポンス例

{
  "store_id": "store_001",
  "generated_at": "2026-05-04T10:00:00Z",
  "expires_at": "2026-05-11T10:00:00Z",
  "location": { "address": "東京都渋谷区...", "municipality_code": "13113" },
  "population": { "age_distribution": { "25_34": 0.148, "35_44": 0.182, ... }, ... },
  "competition": { "density_score": 72, "saturation_index": 1.85, ... },
  "demand": { "estimated_daily_foot_traffic": 45000, "peak_hours": ["12:00","18:00"], ... },
  "economics": { "avg_household_income": 5200000, "disposable_income_index": 115, ... },
  "accessibility": { "walk_score": 92, ... },
  "risk": { "earthquake_risk": "moderate", "flood_risk": "low", ... },
  "scores": { "overall": 78, "demand_score": 82, "competition_score": 65, ... }
}

GET/api/v1/trade-area/{storeId}

キャッシュ済みの商圏分析レポートを取得します。有効期限内のレポートが存在する場合のみ200を返します。

パラメータ

名前	型	必須	説明
storeId	string	はい	店舗識別子

リクエスト例

curl -H "Authorization: Bearer stra_test_your_key" \
  https://stratum.oku-ai.co.jp/api/v1/trade-area/store_001

レスポンス例

{
  "store_id": "store_001",
  "generated_at": "2026-05-04T10:00:00Z",
  "scores": { "overall": 78, ... },
  ...
}

GET/api/v1/competitors

指定座標周辺の競合店舗情報を取得します。業種・半径でフィルタ可能。

パラメータ

名前	型	必須	説明
lat	number	はい	緯度
lng	number	はい	経度
radius_m	number	-	検索半径（100-3000m、デフォルト: 1000）
industry	string	-	業種: restaurant / retail / service / clinic / fitness / education / real_estate
sub_industry	string	-	サブ業種
limit	number	-	取得件数（1-200、デフォルト: 50）

リクエスト例

curl -H "Authorization: Bearer stra_test_your_key" \
  "https://stratum.oku-ai.co.jp/api/v1/competitors?lat=35.6595&lng=139.7004&industry=restaurant"

レスポンス例

{
  "total": 5,
  "area_stats": { "density_score": 72, "saturation_index": 1.85, "business_count_500m": 23 },
  "competitors": [
    {
      "id": "comp_001", "name": "居酒屋A", "distance_m": 120,
      "rating": 3.8, "review_count": 124, "estimated_monthly_revenue": 4500000
    }
  ]
}

POST/api/v1/demand-forecast

店舗の過去売上データをもとに需要予測を生成します。曜日・天候・季節性を考慮した7〜30日間の予測と、スタッフ配置・仕込み量の推奨を返します。

パラメータ

名前	型	必須	説明
store_id	string	はい	店舗識別子
historical_data	array	はい	過去の売上データ（7日分以上。各要素: date, revenue, customers, weather_code?）
forecast_days	number	-	予測日数（1-30、デフォルト: 7）
include_factors	boolean	-	予測因子の内訳を含めるか

リクエスト例

curl -X POST -H "Authorization: Bearer stra_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"store_001","historical_data":[{"date":"2026-04-28","revenue":280000,"customers":82},{"date":"2026-04-29","revenue":310000,"customers":91},{"date":"2026-04-30","revenue":265000,"customers":78},{"date":"2026-05-01","revenue":290000,"customers":85},{"date":"2026-05-02","revenue":340000,"customers":100},{"date":"2026-05-03","revenue":350000,"customers":103},{"date":"2026-05-04","revenue":320000,"customers":94}],"forecast_days":7}' \
  https://stratum.oku-ai.co.jp/api/v1/demand-forecast

レスポンス例

{
  "store_id": "store_001",
  "model_confidence": 0.82,
  "forecast": [
    {
      "date": "2026-05-05", "day_of_week": "月",
      "predicted_revenue": 285000, "predicted_customers": 84,
      "confidence_interval": { "low": 242000, "high": 328000 }
    }
  ],
  "insights": ["火曜は雨予報のため通常比-7%の見込み"],
  "recommended_actions": {
    "staffing": { "mon": { "lunch": 3, "dinner": 5 } },
    "prep_volume": { "mon": 1.05 }
  }
}

POST/api/v1/location-score

複数の候補地を一括でスコアリング・ランキングします。需要・競合・アクセス・経済・コスト効率の5軸で評価し、出店適性を判定します。

パラメータ

名前	型	必須	説明
candidates	array	はい	候補地リスト（1-10件。各要素: id, address, monthly_rent?, seats?）
industry	string	-	業種: restaurant / retail / service / clinic / fitness / education / real_estate
target_revenue	number	-	目標月商（損益分岐計算に使用）

リクエスト例

curl -X POST -H "Authorization: Bearer stra_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"candidates":[{"id":"A","address":"東京都渋谷区神南1-2-3","monthly_rent":1200000,"seats":40},{"id":"B","address":"東京都新宿区歌舞伎町1-5-1","monthly_rent":800000,"seats":30}]}' \
  https://stratum.oku-ai.co.jp/api/v1/location-score

レスポンス例

{
  "rankings": [
    {
      "id": "A", "rank": 1, "overall_score": 82,
      "scores": { "demand": 88, "competition": 65, "accessibility": 95, "economics": 78, "cost_efficiency": 72 },
      "estimated_monthly_revenue": 5800000,
      "estimated_breakeven_months": 8,
      "rent_ratio": 20.7,
      "verdict": "高需要エリア。競合多いが駅近で集客力あり。家賃は高いが回収見込みは早い。"
    }
  ]
}

エラーコード

ステータス	説明
400	リクエストパラメータが不正
401	APIキーが無効または未指定
403	アカウントが無効、またはプランの機能制限
404	リソースが見つからない
429	レート制限超過
500	サーバー内部エラー

Webhook

イベント発生時に登録されたURLへHTTP POSTで通知を送信します。ダッシュボードの「設定 > 外部連携」から最大5エンドポイントを登録できます。

対応イベント

イベント	発火タイミング
simulation.completed	シミュレーション正常完了時
simulation.failed	シミュレーション失敗時
observation.completed	観測ジョブの実行完了時
area.profile_generated	エリアプロファイル生成完了時

署名検証

各リクエストには X-Stratum-Signature ヘッダーが含まれます。 Signing Secret を使ってHMAC-SHA256で検証してください。

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

ペイロード例

{
  "type": "simulation.completed",
  "timestamp": "2026-05-02T10:01:30.000Z",
  "data": {
    "simulationId": "01J...",
    "templateType": "ad_test",
    "areaCode": "13101",
    "personaCount": 100,
    "overallScore": 72.5
  }
}

10回連続で配信が失敗したエンドポイントは自動的に無効化されます。ダッシュボードから再有効化できます。

APIを使い始める

Max 5x 以上のプランでAPIアクセスが利用可能です。B2B連携は別途お問い合わせください。

アカウント作成料金プラン