まるっと検索の検索API v1（Pro プラン）は、日本語の表記ゆれの吸収・同義語・絞り込みを済ませた検索結果を JSON で返します。呼び出し先はストア自身のドメイン上の /apps/marutto-search/search で、API キーや CORS の設定は要りません。検索結果ページ、ヘッダー、コレクションページ、商品ページ、カート、ブログ記事など、ストアフロントのどのページからでも呼べます。チェックアウトとストアの外（Hydrogen・ネイティブアプリ）からは呼べません。
Shopify の検索結果を、
Shopify アプリ「まるっと検索」の検索API は、日本語の表記ゆれまで吸収した検索結果を、ヘッダー、商品ページ、カート、ブログ記事など、ストアの好きな場所に御社のテーマの見た目で並べられる API です。検索結果ページの外でも、お客様が探していた商品に出会える場所が増えます。
Pro プラン（月額 $49.99・14日間無料）に含まれる、検索結果を JSON で返す API です。動く見本を見る
01検索を選ぶ理由
検索窓の先には、
検索窓に入力する人は、買いたいものがほぼ決まっている人です。見つかれば買い、見つからなければ別の店へ離脱してしまいます。第三者の調査でも、その差ははっきり出ています。
- 44%
検索を使った訪問者は全体の24%でしたが、サイト全体の売上の44%を占めていました。購入率は、検索しない人の2.5倍です。
出典：Constructor「Beyond Relevance」（113の小売サイト・検索6億900万回、2024年10〜12月）
- 92%
検索で目的の商品が見つかると、92%がその商品を購入すると答えました（米国の消費者）。
出典：Google Cloud × The Harris Poll（14か国・約13,500人の調査のうち米国の回答、2022年11〜12月）
- 63%
サイト内検索を使う人の63%が、ブランドの公式ECサイトで検索が使いにくく、購入をあきらめたことがあると答えました（「よくある」9.2%と「たまにある」53.7%の合計）。
いずれも第三者による調査で、まるっと検索を導入したときの効果を示すものではありません。導入後の効果は、管理画面の「検索経由売上」で確かめられます。
02仕組み
検索結果を
検索APIは、まるっと検索のエンジンが出した検索結果をJSONで返します。これにより検索結果ページ専用ではなく、ヘッダー、商品ページ、カート、ブログ記事など、ストアフロントのどのページからでも呼べて、デザインのカスタマイズも自由です。
まるっと検索のエンジンがやること
どの商品を、
文章を単語に分けて読み取り、ひらがな・カタカナ・漢字や全角・半角の違いを吸収します。同義語、絞り込みと件数の集計、並び順も、まるっと検索が受け持ちます。
御社のテーマ側で対応すること
どのページに、
検索結果ページ、ヘッダー、商品ページ、カートなど、置く場所も見た目も自由です。仕様どおりに動く参照実装があるので、見た目の部分を書き換えるところから始められます。
そのまま残るもの
テーマのデザインと
まるっと検索は検索結果のデータ（JSON）を返すだけで、テーマのコードには手を入れません。見た目もページの構成も、御社のテーマのままです。
03標準の検索との違い
標準の検索とは、
Shopify にも、オンラインストアの検索と、検索に使える API があります。標準のほうが向いている場面もあるので、あわせて書きます。
| 項目 | Shopify 標準の検索 | まるっと検索 検索API |
|---|---|---|
| 日本語の照合 | Shopify 標準の検索カタカナ・ひらがな・漢字の、3文字以上続く並びで照合します（漢字は2文字の組でも可）。 | まるっと検索 検索API文章を単語に分け、読みの変換で、ひらがな・カタカナ・漢字の違いを吸収します。 |
| ひらがなで検索したとき | Shopify 標準の検索上位に並ぶ目的の商品が、元の表記の半分以下に減ったストアが、70店中46店ありました（検索アプリを入れていないストアの実測）。 | まるっと検索 検索API「わんぴーす」でも、「ワンピース」と同じ8件（商品・記事・ページ）が返ります（見本の結果は実エンジンで確認）。 |
| 入力途中の候補 | Shopify 標準の検索予測検索（Predictive Search API）の対応言語に、日本語は入っていません。 | まるっと検索 検索API確定検索を少ない件数で呼べば、入力の途中から商品と記事の候補を出せます。 |
| 呼び出せる場所 | Shopify 標準の検索Storefront API の search クエリは、Hydrogen などストアの外の独自ストアフロントからも呼べます。 | まるっと検索 検索APIストアフロントのページだけです（アプリプロキシ経由）。ストアの外からは呼べません。 |
| 料金 | Shopify 標準の検索Shopify の料金に含まれます。 | まるっと検索 検索APIまるっと検索の Pro プラン（月額 $49.99）に含まれます。 |
日本語の商品名で探されることが多いストアなら検索API、Hydrogen やアプリなどストアの外から検索を呼びたいなら Storefront API が向いています。
04活用パターン
ストアのどこにでも、
検索API は、検索結果ページ専用ではありません。ストアフロントのページなら、どこからでも呼べます。効果の出やすい置き場所を6つ、動く見本にしました。
見本の店と商品は架空です。検索語の結果は、まるっと検索の実際のエンジンで確かめたものです。
検索結果ページを、
アプリの画面ではなく、テーマの部品で検索結果を組めます。カラー、素材、価格帯、セール中の件数まで集計済みで届くので、絞り込みもそのまま作れます。0件で終わった検索には、ほかのお客様が続けて検索した語も届きます。
効果の出るところ検索からの購入率
カラーや素材を押すと、絞り込んだ結果と件数に替わります。
「ワンピース」の検索結果8件
入力している途中で、
検索窓に入力している途中で、商品と記事の候補を出せます。「送料」のように案内先が決まっている語は、そのページへ直接移動できます。
効果の出るところ検索の途中離脱
コレクションの中を、
コレクションページに、素材・生産国・ブランド・在庫で絞り込める一覧を置けます。商品メタフィールドに入れた情報も、そのまま絞り込みの条件になります。
効果の出るところ回遊と購入率
見ている商品の近くに、
同じ素材や同じタグの商品を、在庫のあるものだけ呼べます。バリエーションの画像と ID も届くので、カラーを選んでそのままカートに入れられます。
効果の出るところ客単価
送料無料まで
足りない金額を価格の下限にして、在庫のある商品を安い順に呼びます。あと少しで送料無料になる人に、届く1点を見せられます。
効果の出るところ客単価
記事の中の商品一覧を、
記事や特集ページに、キーワードで商品一覧を埋め込めます。売り切れた商品は結果から外れるので、書いたあとに手で差し替えなくて済みます。
効果の出るところ記事からの購入と、更新の手間
05計測
API で作った画面の
検索したときと結果を押したときの2つのイベントを送れば、カートへの追加と購入はまるっと検索が紐付け、管理画面の「検索経由売上」に出ます。効果を確かめながら、置き場所を増やしていけます。
01
検索したとき
検索リクエストと同じ session_id と、応答の query_id・measurement_proof を渡します。
02
結果を押したとき
押された商品の product_id と、それが何番目の結果か（0 始まり）を渡します。
03
カートに入れた・買ったとき
送る必要はありません。まるっと検索の Web Pixel が measurement_proof を付け直し、どの検索が売上につながったかを紐付けます。
04
管理画面で見る
検索経由売上、クリック率、クリックされた商品のランキングに反映されます。
この2つを送らないと、検索は動いても検索経由売上は計上されません。検索リクエストに session_id を付け忘れた場合も、分析には数えられません。
06料金
検索API は、
Pro プラン
$49.99/ 月
14日間の無料体験があります
検索API は Pro プランに含まれ、API のための追加料金はありません。検索回数による従量課金もありません。Free・Basic プランでは、検索API は使えません。
Pro プランに含まれるもの（抜粋）
- 検索API v1（検索結果を JSON で受け取り、自社のデザインで描画）
- 購入分析・検索経由売上・改善提案
- 商品メタフィールドの検索と絞り込み
- 独自の言い換え辞書と、検索語ごとの遷移先
- 商品ブースト・フィールドの重み調整・キーワード別の表示ルール
07実装のご相談
実装まで、
まるっと検索の開発元である弊社が、検索API を使った画面の設計から実装までお受けします。置きたい場所とストアの URL を添えて、お気軽にご相談ください。
- 検索結果ページ・コレクションページの作り込み
- ヘッダーの検索、商品ページやカートへの商品一覧の組み込み
- 計測イベントの実装と、検索経由売上の確認まで
費用は、内容を伺ってからお見積もりします。
08導入の流れ
導入は、
1
置き場所を決める
活用パターンを見ながら、まず1か所を選びます。迷ったら弊社にご相談ください。
2
仕様書を確認
仕様書と参照実装（search-api-sample.js）は、インストールしなくてもお読みいただけます。
3
Pro プランで同期する
インストールして Pro プランの無料体験を始めると、商品の索引づくりが始まります。degraded: true が返らなくなったら準備完了です。
4
描画を書き、イベントを送る
参照実装の描画を御社のデザインに置き換え、marutto_search と marutto_result_clicked を送ります。
5
検索経由売上を見る
管理画面で検索からの売上を確かめながら、置き場所を増やしていきます。
無料体験は14日間です。置き場所と見た目を先に決めておくと、期間のうちに効果まで確かめやすくなります。
09実装者に向けて
実装の前に
仕様書から、つまずきやすいところだけを抜き出しました。細かい定義は仕様書をご覧ください。
仕様の要点
- 呼び出し先
- /apps/marutto-search/search（ストア自身のドメイン上。Shopify のアプリプロキシ）
- 認証
- 不要です。ショップは Shopify の署名で特定され、API キーも CORS の設定も要りません
- 必須のパラメータ
- type=search、contract=v1、q（検索語。全件は *）、session_id
- 返る形
- JSON。商品・記事・ページの結果、絞り込みの集計、total・offset・limit
- 件数
- 1回に最大50件。開始位置（offset）は2,000まで
- 回数の上限
- 10秒あたり、ショップごとに50回・訪問者ごとに20回（type=search）
- 応答の速さ
- 検索処理の p95 は100〜250ms（2026年8月の本番実測。稼働は東京リージョン）
- 仕様の維持
- v1 は少なくとも12か月維持し、廃止するときは6か月前にお知らせします
- 呼べない場所
- チェックアウト、サンキューページ、注文状況ページ、ストアの外（Hydrogen・ネイティブアプリ）
- 使えるプラン
- Pro（月額 $49.99・14日間無料体験）。Free・Basic では使えません
API キーも CORS の設定も要りません
呼び出し先は /apps/marutto-search/search。ストア自身のドメインの URL（Shopify のアプリプロキシ）なので、ショップは Shopify の署名で特定されます。
contract=v1 を必ず付けます
付けたリクエストにだけ、仕様書どおりの形が保証されます。v1 は少なくとも12か月維持し、廃止するときは6か月前にお知らせします。フィールドの追加は v1 のまま行います。
degraded を必ず見ます
インストール直後の初回同期中などは degraded: true が返り、結果が空になります。新しいストアは導入初日に必ずここを通るので、準備中の表示か、Shopify 標準の検索への切り替えを用意します。
入力のたびには送りません
type=search の上限は、訪問者ごとに10秒あたり20回です。入力に合わせて呼ぶときは 250〜300ms 待ってから送り、応答に返る query で古い応答を捨てます。
offset の上限は2,000です
「もっと見る」は、次の開始位置が total と 2,000 の両方より小さいときだけ出します。total だけで判定すると、同じ商品が何度も追加されます。
呼べない場所があります
チェックアウト、サンキューページ、注文状況ページからは呼べません。独自ドメインの Hydrogen やネイティブアプリなど、ストアの外からも使えません。
計測のイベントは2つ
検索したときと、結果を押したときに送ります。session_id は検索リクエストに付けたものと同じ値にします。カートへの追加と購入の紐付けは、まるっと検索の Web Pixel が行います。
// 検索したとき
Shopify.analytics.publish("marutto_search", {
query: data.query,
query_id: data.query_id,
session_id: sessionId, // 検索リクエストに付けたものと同じ値
measurement_proof: data.measurement_proof,
result_count: data.total,
});
// 検索結果を押したとき
Shopify.analytics.publish("marutto_result_clicked", {
query_id: data.query_id,
session_id: sessionId,
measurement_proof: data.measurement_proof,
product_id: item.product_id,
position: index, // 0 始まり
});導入初日と、
新しいストアでは、索引ができるまで degraded: true が返ります。Pro 以外のプランでは 403 と code: plan_required が返ります。どちらも検索の不具合ではないので、買い物客にエラーを見せない作りにします。
SALEリネンブレンド ロングワンピース
コットン シャツワンピース
ティアード ロングワンピース索引ができていれば、仕様どおりの形で結果が返ります。
10よくある質問
導入前に
検索API は、どのプランで使えますか？
Pro プラン（月額 $49.99）で使えます。14日間の無料体験があります。Free・Basic プランでは使えません。
Shopify の検索結果ページを、自社のデザインに合わせてカスタマイズできますか？
できます。まるっと検索の検索結果ページは、管理画面から約50項目の見た目を調整できます（コードは要りません）。テーマの部品を使って一から組みたい場合は、検索API で結果を JSON で受け取り、御社のコードで描画します。
Shopify の Storefront API の検索と、何が違いますか？
Storefront API の search クエリは、Hydrogen などストアの外からも呼べる Shopify 標準の API です。まるっと検索の検索API はストアフロントのページからしか呼べない代わりに、ひらがな・カタカナ・漢字の違いを読みの変換で吸収し、検索経由売上の計測まで受け持ちます。ストアの外から呼びたい場合は、Storefront API が向いています。
まるっと検索の検索画面と、一緒に使えますか？
使えます。検索結果ページはまるっと検索の画面のまま、商品ページの関連商品だけを検索API で作る、といった組み合わせもできます。
テーマのコードを書ける人がいなくても使えますか？
検索API の描画は、御社のコードで実装していただく必要があります。社内に書ける人がいない場合は、制作会社か弊社にご相談ください。コードを書かずに使いたい場合は、アプリの検索画面をそのまま使うのが近道です。
実装を頼むと、費用や期間はどのくらいですか？
置く場所の数やデザインによって変わるため、内容を伺ってからお見積もりします。まずは1か所から、というご相談も歓迎です。
Pro プランをやめたら、作った画面はどうなりますか？
検索API は Pro プランの機能なので、プランを変えるとリクエストに 403（code: plan_required）が返るようになります。参照実装のように、そのときはテーマ標準の検索へ切り替わる作りにしておけば、買い物客にエラーは見えません。
Hydrogen やスマホアプリから呼べますか？
いまは呼べません。検索API はアプリプロキシ経由で、ストア自身のドメインの上でだけ動きます。独自ドメインの Hydrogen やネイティブアプリから使いたい場合は、ご要望としてお知らせください。
チェックアウトの中でも使えますか？
使えません。Shopify のチェックアウトは拡張機能がサンドボックスの中で動き、通信先も限られているためです。サンキューページと注文状況ページも同じです。カートページやカートのドロワーからは呼べます。
仕様が変わって、作った画面が動かなくなることはありませんか？
v1 は少なくとも12か月維持し、廃止するときは6か月前にお知らせします。v1 として公開したフィールド名・型・意味と、計測のイベント名は変えません。フィールドの追加は v1 のまま行い、変更が必要なときは v2 として別に用意します。
価格は税込ですか？ 多通貨のストアではどうなりますか？
価格はショップの基準通貨で返り、税込か税抜かは Shopify の設定に従います。Shopify Markets で多通貨にしている場合は、買い物客が見ている通貨と一致しません。為替レートを掛けて換算せず、基準通貨と表示通貨が一致するときだけ価格を描画してください。
検索経由売上を計上するには、何が必要ですか？
検索リクエストに session_id を付けることと、検索したとき（marutto_search）と結果を押したとき（marutto_result_clicked）の2つのイベントを Shopify.analytics.publish で送ることです。カートに入れたときと購入したときの紐付けは、まるっと検索の Web Pixel が自動で行います。