carto-geocoding

CARTO ワークフローでの住所ジオコーディング

住所列はあるものの空間列がない表形式データで、最初に必要となるステップとして、番地や地名を地理座標（ポイントジオメトリ）に変換します。規模に応じて、次の 2 つの方法があります。

• 単一／アドホック（MCP を優先）：少数の住所をジオコーディングする場合（または座標を住所に逆ジオコーディングする場合）、CARTO MCP の geocode ツールが直接応答します。操作は geocode、reverse、capabilities です。ワークフローは不要です。CLI を使用できないサンドボックス化されたチャットホストを含め、あらゆる MCP ホストで実行できます。対話形式のリクエストでは、こちらを優先してください。
• 表全体／繰り返し実行：表全体をジオコーディングする場合や再利用可能なパイプラインを構築する場合は、以下のワークフローパターンを使用します。開発プロセス、JSON 構造、検証については carto-create-workflow を読み込んでください。どちらの方法にも対応しています（接続時は MCP の create_workflow／validate_workflow／run_workflow、それ以外は carto workflows CLI を使用します。アクセス方法の判断については carto-basics/references/access-paths.md を参照してください）。

API トークンを使用した MCP セッションでは、アドホック／作成ツールは非表示になり、読み取り／検出のみが可能です。その場合は CLI に切り替えるか、OAuth で再接続してください。

---

手順

ジオコーディングワークフローは、次のパイプラインに沿って実行します。

Source Table (with address column) -> Geocode -> (Filter successful) -> Save

ステップ 1：ソースデータを読み込む

native.gettablebyname を使用します。入力テーブルには、住所文字列を含む列（例：address、full_address、location）が必要です。

成功条件：ノードの出力が、住所データを含むテキスト列を 1 つ以上持つテーブルであること。

ステップ 2：ジオコーディングする

native.geocode を、次のように使用します。

入力	説明	必須
source	住所データを含むテーブル	はい
address	住所文字列を含む列	はい
country	精度向上のための国フィルター（例："United States"、"United Kingdom"）	いいえ。ただし強く推奨

住所列には、完全な住所（"123 Main St, Springfield, IL 60001"）を指定できます。また、前の native.selectexpression ステップで複数の列（番地＋市区町村＋郵便番号）を連結して作成した値も指定できます。

2 つの出力ハンドル：ジオコーディングコンポーネントは、個別の出力を 2 つ生成します。

• match：ジオコーディングに成功した行です。ポイントジオメトリを含む geom 列と、品質情報（信頼度スコア、マッチタイプ）を含む CARTO_GEOCODE_METADATA JSON 列が追加されます。
• unmatch：ジオコーディングに失敗した行です。geom は NULL になります。

ニーズに応じて、下流のノードを適切なハンドルに接続してください。

成功条件：ジオコーディングノードに住所列と（理想的には）国フィルターが設定されていること。また、エッジが match および／または unmatch の出力ハンドルに接続されていること。

ステップ 3：結果をフィルタリングまたは確認する（任意）

match 出力の場合：

• 必要に応じて、メタデータ列を使用して信頼度でフィルタリングします（例：native.selectexpression を使って CARTO_GEOCODE_METADATA から信頼度を抽出します）。

unmatch 出力の場合：

• 確認と手動修正のため、別のテーブルに保存します。
• よくある失敗原因：誤記、不完全な住所、私書箱、曖昧な地名。

成功条件：信頼度の高いジオコーディング済みの行が分離され、失敗した行が確認用に保存されていること。

ステップ 4：結果を保存する

native.saveastable を使用して、ジオコーディングした出力を永続化します。geom 列には WGS84（EPSG:4326）のポイントが格納され、CARTO Builder での使用や、さらなる分析に備えられます。その後、ワークフローを検証してアップロードします（MCP の create_workflow／validate_workflow、または carto workflows create を使用します）。

---

ジオコーディングの仕組み

ワークフローコンポーネントは、CARTO Analytics Toolbox の関数 GEOCODE_TABLE をラップしています。この関数は次の処理を行います。

• 各行にポイントジオメトリを持つ geom 列を追加します
• 品質情報（信頼度、マッチタイプ）を含む CARTO_GEOCODE_METADATA JSON 列を追加します
• CARTO Location Data Services（LDS）を使用します。ジオコーディングされた行ごとに LDS のクォータを消費します

Analytics Toolbox の LDS_QUOTA_INFO() 関数をクエリして、利用可能なクォータを確認してください。完全修飾名はプロバイダーによって異なります（BigQuery：`carto-un.carto`.LDS_QUOTA_INFO()、Snowflake：CARTO.CARTO.LDS_QUOTA_INFO()、Databricks：専用の AT スキーマにあるストアドプロシージャ）。carto-create-workflow を読み込み、お使いのデータウェアハウスでの AT パスについて references/providers/<provider>.md を参照してください。

---

注意点

• 出力ハンドルは match と unmatch の 2 つです。 間違った方に接続しないでください。match にはジオメトリがあり、unmatch には NULL があります。unmatch ハンドルを空間演算に接続すると失敗します。
• 国のフィルターを強く推奨します。 指定しない場合、曖昧な住所が誤った国に解決される可能性があります（例：「Springfield」は米国の 30 以上の州や他の国にも存在します）。国のパラメーターを指定すると、精度と速度の両方が向上します。
• 住所のフォーマットは重要です。 適切にフォーマットされた住所ほど、良い結果が得られます。"123 Main St, Springfield, IL 60001" は "123 main street springfield" より適しています。利用可能な場合は、市区町村、州／地域、郵便番号を含めてください。
• プロバイダーによる大文字小文字の扱いと SQL 方言。 このスキルの例では小文字の列名を使用しています（BigQuery／Databricks／Postgres／Redshift の規約）。Snowflake では、引用符で囲まれていない識別子は大文字で表示されます（例：CARTO_GEOCODE_METADATA、GEOM）。方言固有の SQL を記述する場合や AT パスを参照する場合は、carto-create-workflow/references/providers/<provider>.md を参照してください。
• 大きなテーブルでは、バッチ処理を検討してください。 数十万行を 1 回の実行でジオコーディングすると、クォータを使い切ったり、タイムアウトしたりする可能性があります。必要に応じてバッチに分割してください。
• ジオコーディングに失敗したデータは確認する価値があります。 unmatch 出力は単なるノイズではありません。郵便番号の欠落、市区町村名の省略形、標準外のフォーマットなど、修正して再度ジオコーディングできるデータ品質の問題が見つかることがよくあります。

---

参考テンプレート

ジオコーディングを扱う Academy のチュートリアルとワークフローテンプレート：

リソース	説明	URL
Geocoding (BigQuery AT)	BigQuery 用 Analytics Toolbox を使用した、手順ごとのジオコーディング	Academy のリンク
Geocoding (Snowflake AT)	Snowflake 用 Analytics Toolbox を使用した、手順ごとのジオコーディング	Academy のリンク
Workflow template: Geocode street addresses	住所から新しい空間データを生成	Academy のリンク

---

よくあるバリエーション

バリエーション	方法
複数列から複合住所を作成	ジオコーディングの前に native.selectexpression ステップを追加し、番地、市区町村、州、郵便番号を 1 つの列に連結します
ジオコーディング + 空間結合	連結します：ジオコーディング -> match -> Spatial Join（例：ポイント・イン・ポリゴンで地域を割り当てる）
ジオコーディング + エンリッチメント	連結します：ジオコーディング -> match -> Buffer/Isochrone -> Enrich（ジオコーディングされた各ポイントの周辺に人口統計データを追加する）
失敗したデータを再処理用に保存	match と unmatch の両方のハンドルを、それぞれ別の native.saveastable ノードに接続します
信頼度でフィルター	ジオコーディング後、native.selectexpression を使ってメタデータ JSON から信頼度を抽出し、その後フィルターします