Belgeler
Ctrl+K Arama Alt+[Alt+] Kılavuzlar
API anahtarını al

API · TikTok Mağazası

TikTok Shop Arama Önerileri API'si

Endpoint (API key)

GET /api/v1/tiktok-shop/öneriler

Send X-API-Anahtarı (or Authorization: Bearer) like every other metered programmatic route. Behavior matches the in-app autocomplete for the same path shape.

Dashboard (session): GET /api/tiktok-shop/öneriler — used when you are logged into the web app. For scripts and integrations, always use the /api/v1/... URL.

Description

Autocomplete for TikTok Shop entities (kategoriler, mağazalar, yaratıcılar, ürünler, videolar): short id + ad rows as the user types.

Request Parameters

Parametre Tür Zorunlu Açıklama Örnek
tür dize Evet Aranacak varlık türü kategoriler, mağazalar, yaratıcılar, ürünler, videolar
q dize Evet Arama sorgusu (kısmi ad eşleşmesi) moda, Nike, seçmek
sınır tamsayı Hayır Maximum number of suggestions to return (default: 10, cap enforced server-side) 5, 10, 20

Response Format

Success Response

Durum Kodu: 200 Tamam

İçerik Türü: application/json

{
  "success": true,
  "suggestions": [
    {
      "id": "category_12345",
      "name": "Fashion & Apparel"
    },
    {
      "id": "category_67890",
      "name": "Fitness Equipment"
    }
  ]
}

Error Response

Durum Kodu: 400 Hatalı İstek

{
  "success": false,
  "error": "Invalid entity type"
}

Durum Kodu: 500 İç Sunucu Hatası

{
  "success": false,
  "error": "Internal server error"
}

Entity Types

Tür Typical id Typical ad Açıklama
kategoriler Category id or path Category label Ürün kategorileri
mağazalar Shop id Mağaza adı TikTok Mağazaları
yaratıcılar Creator id Username or display name Creators / affiliates
ürünler Product id Ürün başlığı Ürünler
videolar Video id Video başlığı Video content

Request Examples

cURL

# Replace {origin} and $WH_API_KEY.
curl -sS -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/suggestions?type=categories&q=fash&limit=10"

curl -sS -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/suggestions?type=shops&q=nike&limit=5"

curl -sS -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/suggestions?type=creators&q=fitness&limit=10"

JavaScript Fetch

// Programmatic (API key)
const response = await fetch(`${ORIGIN}/api/v1/tiktok-shop/suggestions?type=categories&q=fash&limit=10`, {
  headers: {
    Accept: 'application/json',
    'X-API-Key': process.env.WH_API_KEY,
  },
});

const data = await response.json();
console.log(data.suggestions);
// [{ id: "category_123", name: "Fashion & Apparel" }, ...]

Behavior Notes

  • Matching: Case-insensitive partial match on the primary label field for each entity (for creators, both username and display name are considered).
  • Sorting: Results are ordered by a popularity-style signal per entity (e.g. revenue, followers, views) so common matches surface first.
  • Empty input: Very short queries may return an empty öneriler array; the web app often waits until at least 2 characters before calling.
  • Client UX: If you build a typeahead, debounce requests (~300ms) and cache recent tür+q pairs briefly to avoid redundant calls (same idea as the in-app search bar).

Auth and errors

  • /api/v1/tiktok-shop/suggestions uses your API anahtarı and the same metering as other /api/v1/tiktok-shop/* routes.
  • Tutamak 401 / 403 from Kimlik Doğrulama ve 429 from Hız sınırları / Teşekkürler like any other programmatic call.

See also