La ricerca prodotti su TikTok Shop parte da tre domande: cosa si vende in un mercato, cosa c’è dentro una categoria e cosa digitano gli acquirenti quando cercano. SocQ restituiva già ricerca prodotti, cataloghi dei negozi, pagine prodotto, recensioni e vetrine dei creator; 7 migliori API e scraper per TikTok Shop li mette a confronto. Il 2026-11-17 sono stati aggiunti quattro endpoint alla pagina della piattaforma TikTok Shop per rispondere direttamente a queste tre domande.
Questa guida spiega cosa restituisce ciascun endpoint, la richiesta, il prezzo e come concatenarli per analizzare un’intera categoria.
Risposta rapida: invia un corpo JSON a
POST https://api.socq.ai/v1/tiktok-shop/<endpoint>. Salva iltask_idrestituito, interrogaGET /v1/tasks/{task_id}finchéstatusnon èsucceeded, poi leggidata.results.items.
I nuovi endpoint TikTok Shop
1 credito SocQ = $0.005.
| Endpoint | Cosa restituisce | Prezzo |
|---|---|---|
| TikTok Shop Hot Products API | I prodotti più venduti di un mercato, nell’ordine di TikTok Shop, con prezzo, unità vendute, valutazione e negozio | 0.5 crediti ($0.0025) per prodotto |
| TikTok Shop Categories API | L’albero completo delle categorie di un mercato, una riga per categoria con ID, livello e categoria padre | 0.5 crediti ($0.0025) per chiamata |
| TikTok Shop Category Products API | I prodotti di una categoria con prezzo, unità vendute, valutazione, recensioni e negozio | 0.5 crediti ($0.0025) per prodotto |
| TikTok Shop Search Suggestions API | Fino a 20 completamenti di ricerca per l’inizio di una query, in classifica | 0.5 crediti ($0.0025) per chiamata |
Mercati supportati
| Endpoint | Valori di region | Predefinito |
|---|---|---|
| Hot Products | ID, JP, MX, MY, PH, SG, TH, VN | nessuno, obbligatorio |
| Categories, Category Products, Search Suggestions | US, SG, MY, PH, TH, VN, ID, JP, MX | US |
Hot Products non include US. Per la ricerca prodotti negli Stati Uniti, usa Categories e Category Products.
Autenticazione e flusso asincrono dei task
Tutte le richieste si autenticano con una chiave API. Lo stesso header si usa per l’invio, lo stato del task e la lettura dei risultati:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Ogni raccolta viene eseguita come task in background:
submit -> task_id -> queued -> running -> succeeded
\-> failed
La chiamata di invio risponde subito con data.task_id e data.status. Interroga il task con quell’ID:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Quando status è succeeded, la risposta include result_count, credits_amount e la prima pagina di record normalizzati in data.results.items. limit vale 50 per impostazione predefinita e arriva fino a 500. Se results.has_more è true, passa results.next_cursor come cursor per leggere la pagina successiva. Un task fallito riporta error_message.
Ogni endpoint accetta anche un callback_url facoltativo. SocQ invia una POST con il riepilogo del task quando termina; leggi i record dall’endpoint dei task. Un timeout lato client non annulla il task, quindi riprendi con lo stesso ID invece di inviarlo di nuovo. Un 402 significa che l’account ha esaurito i crediti, e un 429 significa che la chiave ha raggiunto un limite di frequenza o di crediti.
Hot Products: cosa si vende in un mercato
La Hot Products API restituisce i prodotti più venduti di un mercato nell’ordine in cui TikTok Shop li classifica. Ogni prodotto ha titolo, price (importo, valuta e stringa formattata), sold_count, rating, reviews_count, seller e immagini, più l’url della pagina prodotto. region è obbligatorio. results_limit vale 50 per impostazione predefinita e accetta valori da 1 a 200. (documentazione)
curl -X POST "https://api.socq.ai/v1/tiktok-shop/hot-products" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"region": "MY", "results_limit": 50}'
Quando usarla: uno snapshot settimanale per mercato per individuare i prodotti in forte crescita, confrontare i prezzi o scegliere prodotti da acquistare e promuovere. I prezzi arrivano nella valuta locale, ad esempio MYR per la Malesia, quindi convertili prima di confrontare i mercati.
Categories: l’albero completo delle categorie
La Categories API restituisce tutte le categorie di un mercato in una sola chiamata. Ogni riga contiene l’id della categoria, name, lo slug in inglese, level, parent_id, is_leaf, path (i nomi delle categorie superiori), cover_url e region. Le categorie di primo livello hanno parent_id: null e level: 1, quindi puoi ricostruire la gerarchia come albero o tenerla come tabella di lookup piatta. (documentazione)
curl -X POST "https://api.socq.ai/v1/tiktok-shop/categories" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"region": "US"}'
Quando usarla: una volta per mercato, poi metti in cache il risultato. Ti servono gli ID per Category Products, e l’albero è utile per mappare le categorie di TikTok Shop sul tuo catalogo.
Category Products: sfoglia una categoria come un acquirente
La Category Products API accetta un category_id numerico ottenuto dalla Categories API e restituisce i prodotti di quella categoria con titolo, prezzo, unità vendute, valutazione, recensioni, negozio e immagini. region vale US per impostazione predefinita. results_limit vale 30 per impostazione predefinita e accetta valori da 1 a 500. (documentazione)
curl -X POST "https://api.socq.ai/v1/tiktok-shop/category-products" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"category_id": "601450", "region": "US", "results_limit": 30}'
Quando usarla: per confrontare le fasce di prezzo tra sottocategorie o per osservare come cambiano nel tempo i best seller di una categoria.
Search Suggestions: cosa digitano gli acquirenti
La Search Suggestions API accetta in query l’inizio di una ricerca di shopping e restituisce fino a 20 completamenti, in classifica a partire da 1, nell’ordine in cui li suggerisce TikTok Shop. Ogni riga contiene la keyword, la query che hai inviato, il suo rank e la region. region vale US per impostazione predefinita. (documentazione)
curl -X POST "https://api.socq.ai/v1/tiktok-shop/search-suggestions" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "phone case", "region": "US"}'
Quando usarla: ricerca di parole chiave per schede prodotto, annunci e contenuti. Per phone case, il primo completamento nell’esempio della documentazione è phone cases 17 pro max, che mostra per quali modelli di telefono comprano gli acquirenti. Passa i completamenti a TikTok Shop Search per vedere quali prodotti si posizionano per ciascuno.
Analisi di una categoria in tre chiamate
Una tipica sessione di ricerca per un mercato:
- Chiama Categories una volta per il mercato e salva l’albero (0.5 crediti).
- Scegli le categorie finali che ti interessano (
is_leaf: true) e chiama Category Products per ciascuna. - Chiama Search Suggestions con le parole chiave principali dei prodotti di ogni categoria per vedere come gli acquirenti formulano le loro ricerche.
Dieci categorie da 30 prodotti ciascuna fanno 300 prodotti, ovvero 150 crediti. Aggiungi l’albero (0.5) e dieci chiamate di suggerimenti (5) e la sessione costa 155.5 crediti, circa $0.78. In un mercato supportato da Hot Products, uno snapshot da 50 prodotti aggiunge 25 crediti ($0.125).
Leggi i campi con attenzione
Le righe dei prodotti usano la stessa struttura normalizzata nei tre endpoint di prodotto. Come per gli altri campi SocQ, un valore che la fonte non fornisce è null, non 0. Negli esempi della documentazione, rating, reviews_count e sold_count sono null per i prodotti mostrati, quindi considera vendite o valutazioni mancanti come sconosciute, non come zero, prima di ordinare i prodotti in base a questi valori.
Per approfondire un singolo prodotto, passa il suo url alla TikTok Shop Product API, che al momento serve solo la regione US, e alla Product Reviews API. Per altri modi di ottenere dati di TikTok Shop, vedi Alternative alle API di TikTok Shop. I prodotti venduti durante le dirette LIVE sono coperti dalla TikTok Live Shopping API nella guida ai nuovi endpoint TikTok.
FAQ
Serve un account venditore o partner di TikTok Shop?
No. Gli endpoint leggono dati pubblici di TikTok Shop, e ti autentichi con una chiave API SocQ.
Perché Hot Products rifiuta US?
US non è tra i suoi valori di region. Hot Products copre ID, JP, MX, MY, PH, SG, TH e VN. Gli altri tre endpoint supportano US e lo usano come valore predefinito.
Da dove arrivano gli ID delle categorie?
Dalla Categories API. L’id di ogni riga è il category_id che accetta Category Products, per la stessa region.
Come viene addebitato ciascun endpoint?
Categories e Search Suggestions costano 0.5 crediti per chiamata, indipendentemente da quante righe restituiscono. Hot Products e Category Products costano 0.5 crediti per prodotto restituito.
Quanti suggerimenti restituisce una query?
Fino a 20, in classifica a partire da 1 nell’ordine di TikTok Shop.
TIKTOK SHOP API
Prova il flusso di lavoro con un URL pubblico di TikTok Shop
Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.
Scopri le API di TikTok Shop