API を通じて Shoply AI Search にアクセスする方法

Shoply AI Search API connecting backend code to storefront product search results

はい。オンサイトのウィジェットを読み込んだり、Shopify ストアフロント経由でリクエストを送信したりしなくても、ご自身のバックエンドから Shoply AI Search をプログラムでクエリできます。

標準の検索 API は、Forever Free を含む、AI Search が含まれるすべての Shopify プランで利用できます。API リクエストは、ストアフロントのウィジェット経由で行われる検索と同じ月間検索枠を使用します。最新の上限については、料金ページをご覧ください。

より高い上限、サービスレベル契約、カスタムデータソース、または Shoply にインデックスされた Shopify カタログを使用しない統合が必要な場合は、Enterprise プランについてお問い合わせください。

始める前に

検索したいカタログがある Shopify ストアに Shoply AI をインストールし、最初の製品インデックス作成が完了するまで待ってください。ストアの永続的な myshopify.com ドメインが必要です。例えば次のようなものです。

text


your-store.myshopify.com

API は任意のバックエンド環境から呼び出せます。標準の製品検索エンドポイントでは、別個の API キーは必要ありません。これは、Shoply がストアフロント検索体験で表示できるものと同じ公開カタログ情報を返すためです。

エンドポイント

text


POST https://api.shoplyai.ai/product_query_v2
Content-Type: application/json

リクエストボディ

項目	必須	説明
`store_key`	はい	ストアの永続的な `myshopify.com` ドメイン
`query`	はい	少なくとも `keywords` フィールドを含む JSON エンコード済み文字列
`start`	いいえ	ページネーション用の 0 始まりの結果オフセット。デフォルトは `0`
`limit`	いいえ	返す製品の最大数。デフォルトは `4`

query はリクエストボディ内の JSON 文字列であり、ネストされた JSON オブジェクトではありません。例えば、検索フレーズ waterproof hiking boots は次のように送信されます。

json


"{\"keywords\":\"waterproof hiking boots\"}"

cURL の例

your-store.myshopify.com を、ストアの永続的な Shopify ドメインに置き換えてください。

bash


curl --request POST "https://api.shoplyai.ai/product_query_v2" \
  --header "Content-Type: application/json" \
  --data '{
    "store_key": "your-store.myshopify.com",
    "query": "{\"keywords\":\"waterproof hiking boots\"}",
    "start": 0,
    "limit": 8
  }'

JavaScript の例


// Build the inner query separately because the API expects it as a JSON-encoded string.
const searchQuery = JSON.stringify({
  keywords: "waterproof hiking boots"
});
 
const response = await fetch("https://api.shoplyai.ai/product_query_v2", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    store_key: "your-store.myshopify.com",
    query: searchQuery,
    start: 0,
    limit: 8
  })
});
 
if (!response.ok) {
  throw new Error(`Shoply search failed with status ${response.status}`);
}
 
const results = await response.json();
console.log(results.docs);

Python の例

python


import json
import requests
 
# The query value is encoded separately to match Shoply's structured search contract.
payload = {
    "store_key": "your-store.myshopify.com",
    "query": json.dumps({"keywords": "waterproof hiking boots"}),
    "start": 0,
    "limit": 8,
}
 
response = requests.post(
    "https://api.shoplyai.ai/product_query_v2",
    json=payload,
    timeout=30,
)
response.raise_for_status()
 
results = response.json()
print(results["docs"])

レスポンス

成功したリクエストは次を返します。

json


{
  "num_results": 2,
  "docs": [
    {
      "product_id": "gid://shopify/Product/1234567890",
      "url": "https://your-store.example/products/example-product",
      "product_name": "Example Product",
      "brand": "Example Brand",
      "current_price": "129.00",
      "currency": "USD",
      "main_image": "https://cdn.shopify.com/example-product.jpg",
      "selected_variant_id": "gid://shopify/ProductVariant/1234567891"
    }
  ],
  "display_filters": []
}

num_results は一致した製品の総数です。
docs には、要求されたページに対するランキング済みの製品が含まれます。
display_filters には、価格、ブランド、色、その他カタログ固有の属性など、利用可能なフィルターが含まれます。

製品オブジェクトには、ストアのカタログ、バリアント、価格設定、Shoply の構成に応じて追加フィールドが含まれる場合があります。クライアントは必要なフィールドを使用し、不明なフィールドは安全に無視してください。

ページネーション

追加の結果を取得するには、start と limit を使用します。例えば、start: 0 と limit: 8 で 8 件の製品をリクエストした後、次のページは以下でリクエストします。

json


{
  "start": 8,
  "limit": 8
}

start + docs.length が num_results 以上になった時点、または docs が空になった時点で停止してください。

プランと統合に関する注意

カスタムストアフロントでも会話機能が必要な場合は、ヘッドレス Shopify ストアフロントにチャットを追加するをご覧ください。

標準 API 検索はセルフサービスで利用でき、オンサイトウィジェットは不要です。
製品インデックスを最新の状態に保つため、Shopify ストアは Shoply AI に接続されたままである必要があります。
API 検索とストアフロント検索は、Shopify プランの月間検索枠を共有します。
キャッシュ、ロギング、リトライ、アクセス制御を一元化したい場合は、呼び出しをバックエンド側に維持してください。
カスタム認証、保証されたスループット、SLA、Shopify 以外のカタログ、または公開プランの上限を超える要件がある場合は、Enterprise サポートについてお問い合わせください。

ストアキーの確認や本番統合の計画についてサポートが必要な場合は、Shoply AI にお問い合わせください。