UCP ロケーション検索・照会 AI エージェントが「近くの実店舗」と「在庫のある店」を探せるように

図解 ： UCP ロケーション検索・照会（dev.ucp.common.location.search / lookup） UCP / Storefront MCP / 新機能 UCP ロケーション検索・照会 AI エージェントが「近くの実店舗」と「在庫のある店」を探せるように UCP 2026-08-25 から、Shopify ストアフロントの MCP エンドポイントで search_locations / lookup_locations の 2 ツールが使えるようになった。店名・都市・距離・取扱商品でマーチャントの実店舗を絞り込める。任意で使う新機能なので、使わないなら対応は不要。 このページの構成 そもそも何が変わるのか（30秒で理解） 仕組み図解 ： 検出 → ネゴシエーション → ツール呼び出し 2 つのツール ： search と lookup パラメータと上限の早見表 非対応のもの・影響範囲 対応手順（4ステップ） 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何が変わるのか UCP 2026-08-25 から、Shopify ストアフロントが UCP の location ケーパビリティ （ dev.ucp.common.location.search / dev.ucp.common.location.lookup ）に対応した。 エージェントはこれをネゴシエーションすると、 マーチャントの実店舗を探し、店名・都市・距離で絞り込み、買い手が欲しい商品を扱っている店を確認 できる。 これまで ： 実店舗は見えない UCP 経由のエージェントから、マーチャントの実店舗情報を引く手段としてこの 2 ツールは提供されていなかった。 これから ： 店舗を検索・照会できる ストアフロント MCP エンドポイントに search_locations と lookup_locations が出てくる。任意の新機能で、使わなければ変更不要。 2 仕組み図解 ： 検出 → ネゴシエーション → ツール呼び出し retail location の定義 ： 有効（active）で、マーチャントが管理し、対面販売用に設定し、 Physical storefront として有効化したロケーション。 MCP エンドポイントは https://{storedomain}/api/ucp/mcp 。 3 2 つのツール ： search と lookup search_locations ショップの実店舗を一覧・絞り込み 空の location オブジェクト → 最初のページを返す query ： 店名と都市にマッチ distance ： 明示的な中心点＋最大半径（メートル） filters.items ： 取扱商品で絞り込み 既定 10 件、 pagination.limit で最大 250 件 次ページはレスポンスの pagination.cursor を渡す lookup_locations ID を指定して店舗を取得 ID 例 ： gid://shopify/Location/123 処理するのは 最初の重複しない 10 ID まで 超えた場合はレスポンスに batch_limit_applied メッセージ 残りは別リクエストで送る 各ロケーションに含まれる情報 id name 店舗名 address 住所 geo 座標（設定時のみ） 4 パラメータと上限の早見表 項目 仕様 注意点 search の件数 既定 10 pagination.limit で最大 250 次ページは pagination.cursor lookup の ID 数 最大 10 （重複除外後） 超過時は batch_limit_applied が返るので分割送信 filters.items 最大 10 商品バリアント ID 全バリアントが取り扱い可能 な店舗だけがマッチ（AND 条件） distance 明示的な center ＋ 最大半径（メートル） 中心点は買い手が共有した位置のみ。Shopify は文脈や IP から推定しない query 店名・都市にマッチ — 商品マッチの意味 既存の店舗在庫表示（store availability）ルールに従う 在庫数ではない 受け取り保証・取り置きでもない 5 非対応のもの・影響範囲 Shopify が対応していないもの（送ると invalid_input エラー） 非対応 hours フィルタ 営業時間での絞り込み。 非対応 amenities フィルタ 店舗設備での絞り込み。 非対応 カスタムフィルタ 独自のフィルタ条件。 非対応 serves リレーション distance 以外のリレーション。 これらは 無視されず invalid_input エラーになる 。また、 選択した店舗での受け取り（Pickup）チェックアウトは非対応 。 影響を受ける／受けない 影響あり 対象になるのは ストアフロント MCP エンドポイントを UCP 2026-08-25 で使い、location ケーパビリティのどちらかをネゴシエーションするプラットフォーム／エージェント。 影響なし 対象外なのは retail location の無いショップ（ケーパビリティもツールも掲載されない）。ケーパビリティを宣言しない、または以前の UCP バージョンでネゴシエーションする連携。 6 対応手順（4ステップ） 1 agent profile で宣言 dev.ucp.common.location.search と .lookup を version 2026-08-25 で宣言。 2 プロファイルを確認 ショップのプロファイルに掲載されているときだけロケーションツールを呼ぶ。 3 位置は同意ベースで distance.center は買い手が共有を選んだ位置からのみ送る。 4 カート／チェックアウトで再確認 商品マッチは暫定扱い。「用意できています」と伝える前に在庫と配送方法を確認。 現在ロケーションを使っていない連携は変更不要。 宣言しない限り挙動は変わらない、完全なオプトイン機能。 7 技術者が押さえるべき5つのポイント 1. ケーパビリティ駆動で呼び分ける retail location の無いショップではケーパビリティもツールも出てこない。 /.well-known/ucp のプロファイルを見て、掲載がある場合だけツールを呼ぶ実装にする。 2. 未対応パラメータはエラーになる hours / amenities / カスタムフィルタ / serves は 無視されず invalid_input 。汎用 UCP クライアントを使い回す場合、Shopify 向けにはこれらを外して送る。 3. ページングとバッチ上限を前提に組む search は既定 10・最大 250 件、カーソルで続きを取得。lookup は重複除外後 10 ID まで、超過は batch_limit_applied を見て分割再送。 4. 位置情報は買い手の明示共有だけ distance.center は買い手が共有を選んだ位置からのみ。Shopify も文脈や IP から中心点を推定しない。プライバシー設計上の前提として扱う。 5. filters.items は「暫定マッチ」でしかない 最大 10 バリアントの AND 条件で、既存の店舗在庫表示ルールに従う。 在庫数でも受け取り保証でも取り置きでもない 。さらに選択店舗での Pickup チェックアウトは非対応なので、エージェントの応答文言は「在庫がありそうな店舗」止まりにし、確定はカート／チェックアウトで行う。 8 業務に活かせる3つのユースケース USE CASE 1 ショッピングエージェントで「近くの店舗」案内 課題 実店舗を持つブランドで、AI エージェント経由の買い手に店舗の場所を案内できず、オンラインとオフラインの導線が分断されている。 打ち手 買い手が位置共有に同意したら search_locations に distance（中心点＋半径メートル）を渡し、近隣店舗を名前・住所付きで提示。 効果 エージェント上の会話から実店舗への来店導線をつくれる。 技術メモ 位置共有がなければ distance は使わず、query（店名・都市）での検索にフォールバックする設計にする。 USE CASE 2 「まとめて買いたい商品を全部扱う店」を探す 課題 コーディネート一式やギフトセットなど複数商品を店頭で見たい買い手に、全部そろう店舗を案内したい。 打ち手 買い手が選んだバリアント ID（最大 10）を filters.items に入れて検索。全バリアントが取り扱い可能な店舗だけが返る。 効果 「行ったのに無かった」を減らす方向の店舗提案ができる。 技術メモ 結果は在庫数・取り置きではないので、文言は「取り扱いのある店舗」にとどめ、確定はカート／チェックアウトで確認する。 USE CASE 3 エージェント連携プラットフォームの店舗データ同期 課題 複数マーチャントを扱うプラットフォームで、各ショップの実店舗一覧を取得・更新する仕組みが必要。 打ち手 プロファイルに location ケーパビリティがあるショップだけ対象にし、 search_locations を pagination.limit 250 ＋カーソルで全件取得。以降は保存した ID を lookup_locations で再取得。 効果 店舗情報（名前・住所・座標）を UCP 標準の手段でまとめて扱える。 技術メモ lookup は 10 ID 単位でバッチ化し、 batch_limit_applied を検知したら残りを再送。geo はマーチャントが設定した場合のみなので欠損を許容する。 9 提案で使える1行サマリ 「UCP 2026-08-25 で、AI エージェントが Shopify マーチャントの 実店舗を検索・照会し、欲しい商品を扱う店を絞り込める ようになった。 オプトインで既存連携は無影響 。位置は買い手の同意ベース、商品マッチは暫定扱いでチェックアウト時に確定するのが前提。」 source ： shopify.dev / changelog / discover-a-merchant-s-retail-stores-with-ucp-location-search-and-lookup 原文公開日 2026-10-22