carto-trade-area-analysis

商圏分析

候補地の周囲に商圏エリアを定義する CARTO ワークフローを構築し、データを付加して、出店場所の選定、看板の設置、またはカバレッジ分析に向けて候補地を採点・順位付けします。

前提条件: 開発プロセス、JSON 構造、検証については carto-create-workflow を読み込んでください。接続時の MCP サーバーのワークフローツール（create_workflow、validate_workflow、run_workflow）と、それ以外の場合の carto workflows CLI の両方のアクセス方法を説明しています。ルーティングの手がかり: carto-basics/references/access-paths.md。

アドホックな商圏: 少数の地点を対象とする単発の等時間圏には、MCP ツールの calculate_isolines を使用してください（OAuth 経由、または Allowed APIs に LDS を含むトークンセッションで利用できます）。以下のワークフローパターンは、テーブル規模で繰り返し実行する分析向けです。

---

手順

商圏分析ワークフローは、常に次のパイプラインに従います。

Candidate Locations → (Filter) → Catchment Areas → Spatial Index → Enrich → Aggregate → Score/Rank → Save

ステップ 1: 候補地を読み込む

native.gettablebyname を使用して、店舗、看板、POI、または候補地を表す任意のポイントデータセットを読み込みます。

成功条件: ノードの出力に、ジオメトリ列（例: geom）と一意の地点識別子を含むテーブルがあること。

ステップ 2: 候補地をフィルタリング／制限する（任意）

native.wheresimplified を使用して、候補地を絞り込みます（例: 特定の都市、カテゴリ）。指標に基づいて上位 N 件を取得するには、native.orderby と native.limit を組み合わせます（例: 売上上位 50 件）。

成功条件: 出力に分析に関連する候補地のみが含まれていること。早い段階で候補地を減らすことで、後続処理の組み合わせが爆発的に増えるのを防げます。

ステップ 3: 商圏エリアを生成する

用途に応じて商圏の生成方法を選択します。

方法	コンポーネント	使用する場面	主なパラメーター
等時間圏	native.isolines	出店場所の選定、小売業 — 道路網に沿った現実的なエリア	mode: 車／徒歩；type: 時間／距離；range: 秒またはメートル
バッファー	native.buffer	看板のカバレッジ、近接性 — シンプルな幾何学的円	distance: メートル

等時間圏とバッファーの比較: 等時間圏は道路網に沿った現実的な形状の商圏を生成しますが、CARTO LDS API の呼び出しが必要です。バッファーは幾何学的な円のみを生成します。よりシンプルで高速なため、近接性分析や看板のカバレッジに適しています。

成功条件: 各候補地に、その商圏エリアを表すポリゴンが関連付けられていること。

ステップ 4: 商圏を空間インデックスに変換する

native.h3polyfill または native.quadbinpolyfill を使用して、商圏ポリゴンをグリッドセルに分割します。解像度は、使用するエンリッチメントデータセットと一致させる必要があります。

成功条件: 出力に地点ごと・グリッドセルごとの行があり、空間インデックス列と地点識別子の両方が保持されていること。

ステップ 5: データを付加する

グリッドセルを空間フィーチャーデータセットと結合するか、native.h3enrich を使用します。

• JOIN アプローチ: インデックス作成済みのエンリッチメントテーブルを native.joinv2 または native.spatialjoin で結合します
• エンリッチアプローチ: native.h3enrich を使用して CARTO の Data Observatory から変数を取得します

成功条件: 各グリッドセルの行に、エンリッチメント変数（例: 人口、所得、歩行者通行量）が付加されていること。

ステップ 6: 地点単位に集計し直す

native.groupby を使用して、グリッドセル単位の行を地点ごとに 1 行へまとめます。

• グループ化の基準: 地点識別子列
• 集計: population,sum,income,avg（列とメソッドの組をコンマ区切りで指定）

成功条件: 出力に候補地ごとに 1 行ずつ含まれ、エンリッチメント指標が集計されていること。

ステップ 7: 採点して順位付けする

3 部構成のパターンです（手法全体については carto-composite-scoring を参照してください）。native.normalize で各変数を [0,1] に正規化し、native.selectexpression で複合スコアを算出します。例: normalized_population * 0.4 + normalized_income * 0.3 + normalized_traffic * 0.3。最後に、native.orderby（降順）と native.limit（上位 N 件）で順位付けします。

成功条件: 複合スコアと、スコアの算出に寄与した正規化済み変数を含む、候補地の順位付きリストが得られること。

ステップ 8：保存

native.saveastable を使用して、ランキング結果を永続化します。

成功条件：検証済みのワークフローが作成され、create_workflow（MCP）または carto workflows create（CLI）でアップロードできます。

---

注意点

• プロバイダーの大文字・小文字の扱いと SQL 方言。 このスキルでは小文字の列名（geom、population、income、normalized_population など）を使用します。これは BigQuery／Databricks／Postgres／Redshift の規則です。Snowflake では、引用符で囲まれていない識別子は大文字として扱われるため、GEOM、POPULATION、INCOME、NORMALIZED_POPULATION のように参照してください。大文字・小文字の規則と SQL 方言の対応については、carto-create-workflow/references/providers/<provider>.md を参照してください。
• アイソクロンとルートのコンポーネントは CARTO の LDS API を呼び出すため、API アクセスが有効な有効な接続が必要です。バッファーには必要ありません。
• 距離マトリックスのクロス結合は、ロケーションやグリッドセルが多数あると処理量が膨大になる可能性があります。パイプラインを適切な規模に保つため、まず候補をフィルタリングして絞り込んでください（ステップ 2）。
• H3 解像度は、エンリッチメントデータセットの解像度と一致させる必要があります。解像度を選ぶ前に、エンリッチメントテーブルのインデックス列を確認してください。
• バッファーの距離の単位はメートルです。等値線の範囲の単位は、type=time の場合は秒、type=distance の場合はメートルです。
• native.commercialhotspots コンポーネントでは、variablecolumns に Python 形式のリスト文字列（['col1', 'col2']）を、weights にカンマ区切りの値を指定する必要があります。他のコンポーネントとは形式が異なります。
• エンリッチメント結果をロケーションに集約して戻す場合（ステップ 6）、GROUP BY にはグリッドセルのインデックスではなく、ロケーション識別子を指定してください。グリッドセルでグループ化すると、ロケーションごとではなくセルごとの結果になります。
• 競合相手との近接性を調べるために native.h3distance を使用する場合、出力はグリッドベースです。ロケーションごとの距離指標を得るには、ロケーションテーブルに結合してください。

---

参照テンプレート

以下のファイルは、このスキルディレクトリにある動作例です。

ファイル	説明
isochrones_from_points.json	ボストンの小売店舗 — LDS API を使った徒歩 5 分のアイソクロン。native.isolines は v2 です（小文字のワイヤー値を使う mode リスト、customoptions／traveltime_* 入力）。
identify_best_billboards.json	看板設置場所のスコアリング — バッファー、エンリッチメント、正規化、重み付き複合スコア、上位 N 件
commercial_hotspots.json	商業ホットスポットの検出 — 競合相手までの H3 距離、重み付きホットスポット分析

コンポーネントのバージョンを更新する。 テンプレートの各ノードでは、取得時点でのバージョンが data.version に固定されています。ネイティブコンポーネントのバージョンが上がると（例：native.isolines v1 から v2 への更新で、移動手段と customoptions および traveltime_* 入力が追加）、古いテンプレートも解析はできますが、verify-remote の警告が表示され、新しい入力が反映されません。更新するには、ライブスキーマを読み取り、ノードの data.version と inputs を同時に更新してください。Selection の値は carto-create-workflow/SKILL.md と照合してください。options に表示ラベルが記載されていても、ワイヤー値は小文字または snake_case 形式です。

---

よくあるバリエーション

バリエーション	方法
小売店舗の設置場所選定	アイソクロン（徒歩／車） -> H3 ポリフィル -> 人口統計データでエンリッチメント -> 人口と所得に基づいてスコアリング
看板／OOH の設置	バッファー -> H3 ポリフィル -> オーディエンス／交通量データでエンリッチメント -> 正規化 + 重み付きスコア -> 上位 N 件
商業ホットスポットの検出	H3 グリッド -> 競合相手との近接性に native.h3distance を使用 -> 重みと p 値のしきい値を指定して native.commercialhotspots を使用
車での所要時間に基づくカバレッジ分析	アイソクロン（車、複数の範囲） -> 結合 -> ディゾルブして総カバレッジ領域を特定
徒歩圏の比較	アイソクロン（徒歩、5／10／15 分） -> 各範囲をエンリッチメント -> 各範囲で捕捉された人口を比較
フランチャイズのテリトリー計画	候補地ごとにアイソクロンを作成 -> 重なりを確認 -> 重複しない候補地を抽出 -> 残った候補地をスコアリング