Shoply AI Search API の使い方

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 にお問い合わせください。