Så använder du Shoply AI Search API

Ja. Du kan fråga Shoply AI Search programmatiskt från din egen backend utan att ladda widgeten på webbplatsen eller skicka begäran via din Shopify-storefront.

Det vanliga sök-API:et är tillgängligt med alla Shopify-planer som inkluderar AI Search, inklusive Forever Free. API-begäranden använder samma månatliga sökvolym som sökningar som görs via storefront-widgeten. Se de aktuella gränserna på vår prissida.

Om du behöver högre gränser, ett service level agreement, en anpassad datakälla eller en integration som inte använder en Shoply-indexerad Shopify-katalog kan du kontakta oss om en Enterprise-plan.

Innan du börjar

Installera Shoply AI i den Shopify-butik vars katalog du vill söka i och låt den initiala produktindexeringen bli klar. Du behöver butikens permanenta myshopify.com-domän, till exempel:

your-store.myshopify.com

API:et kan anropas från vilken backend-miljö som helst. En separat API-nyckel krävs inte för den vanliga endpointen för produktsökning eftersom den returnerar samma offentliga kataloginformation som Shoply kan visa i sökupplevelsen i storefronten.

Endpoint

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

Begärandetext

query är en JSON-sträng i begärandetexten, inte ett nästlat JSON-objekt. Till exempel skickas sökfrasen waterproof hiking boots som:

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

cURL-exempel

Ersätt your-store.myshopify.com med din butiks permanenta Shopify-domän:

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-exempel

// 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-exempel

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"])

Svar

En lyckad begäran returnerar:

{
  "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 är det totala antalet matchande produkter.
• docs innehåller de rankade produkterna för den begärda sidan.
• display_filters innehåller tillgängliga filter som pris, varumärke, färg eller andra katalogspecifika attribut.

Produktobjekt kan innehålla ytterligare fält beroende på butikens katalog, varianter, prissättning och Shoply-konfiguration. Klienter bör använda de fält de behöver och på ett säkert sätt ignorera okända fält.

Paginering

Använd start och limit för att begära fler resultat. Till exempel, efter att ha begärt åtta produkter med start: 0 och limit: 8, begär nästa sida med:

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

Sluta när start + docs.length är större än eller lika med num_results, eller när docs är tom.

Anmärkningar om planer och integration

Om din anpassade storefront också behöver konversation kan du lägga till chatt i en headless Shopify-storefront.

• Standard-API-sökning är self-service och kräver inte widgeten på webbplatsen.
• Din Shopify-butik måste förbli ansluten till Shoply AI så att dess produktindex kan hållas uppdaterat.
• API-sökningar och storefront-sökningar delar den månatliga sökvolymen för din Shopify-plan.
• Behåll anropet i din backend om du vill centralisera cachning, loggning, återförsök eller åtkomstkontroll.
• Kontakta oss för Enterprise-support om du behöver anpassad autentisering, garanterad genomströmning, ett SLA, en katalog som inte är Shopify eller gränser utöver de publicerade planerna.

För hjälp med att bekräfta din store key eller planera en produktionsintegration, kontakta Shoply AI.