API unificataAPI per i social mediaGuida per sviluppatori

API unificata per i social media: un’unica API per i dati social pubblici

Una sola chiave API, un solo modello di attività e uno schema normalizzato per raccogliere dati pubblici di social, annunci, e-commerce, mappe, app store e SEO su 27 piattaforme.

SocQAggiornato il 9 novembre 202612 min di lettura

Aggiungere una seconda piattaforma social a un prodotto raramente raddoppia il lavoro di integrazione. Ogni rete introduce un modello di autenticazione, un vocabolario di risorse, una struttura delle risposte, uno schema di paginazione, una tassonomia degli errori e un calendario di manutenzione diversi. Ventisette integrazioni separate possono diventare ventisette sistemi separati.

La Social Media API di SocQ riunisce i dati pubblici dietro un’unica chiave API, un unico flusso di attività asincrone e un modello di record normalizzato. Il catalogo attuale comprende più di 170 endpoint mirati su 27 piattaforme: social network, librerie degli annunci, e-commerce, mappe, app store e SEO.

SocQ public data catalog

Risposta rapida: chiama POST /v1/{platform}/{resource} con gli input richiesti da quella risorsa, conserva l’ID attività restituito e interroga lo stato dell’attività tramite l’endpoint comune. I record condividono convenzioni normalizzate per piattaforma, risorsa, identità, autore, metriche, contenuti multimediali e timestamp, mantenendo i valori specifici della fonte in campi espliciti e in extra.

Che cos’è un’API unificata per i social media?

Un’API unificata è uno strato di astrazione sopra più integrazioni di piattaforma. Invece di insegnare alla tua applicazione un nuovo sistema di autenticazione e un formato di risposta incompatibile per ogni fonte, integri un’unica specifica e scegli piattaforma e risorsa nella route.

“Unificata” non deve significare “fingere che tutte le piattaforme siano identiche”. Un’offerta di lavoro su LinkedIn non è un video di TikTok, un annuncio di Marketplace non è un profilo di Instagram e un luogo di Google Maps non ha un equivalente utile su Reddit. Un modello unificato responsabile standardizza i concetti davvero comuni e conserva la semantica specifica della fonte dove le piattaforme differiscono.

API per dati pubblici e API per account collegati

Nei risultati di ricerca, sotto “API unificata per i social media” compaiono due prodotti diversi.

Un’API per account collegati usa OAuth per consentire agli utenti autorizzati di pubblicare, pianificare post, gestire commenti o messaggi e leggere le statistiche private degli account. È la categoria giusta per i software di gestione dei social media.

Un’API per dati pubblici raccoglie le risorse supportate e visibili pubblicamente per ricerca, monitoraggio, analisi o arricchimento dei dati. SocQ appartiene a questa seconda categoria. I suoi endpoint non pubblicano post, non inviano DM, non gestiscono annunci e non sostituiscono le API ufficiali per le azioni autorizzate sugli account.

Molti prodotti hanno bisogno di entrambe: API ufficiali o per account collegati per le scritture e i dati soggetti a permessi, più uno strato di dati pubblici per le fonti esterne supportate.

27 piattaforme e più di 170 endpoint

La copertura si capisce meglio per categoria che con un breve elenco di loghi.

CategoriaEsempi nel catalogoCosa si raccoglie di solito
SocialInstagram (17+), TikTok (18), X (15), Facebook (14), YouTube (12), LinkedIn (11), Reddit (6), Pinterest (4), Threads (3), più Douyin, Rednote, Snapchat, Bluesky, Twitch, Truth Social, KwaiPersone, post, commenti, ricerca
Librerie degli annunciFacebook, TikTok, Google e LinkedIn Ad LibraryCreatività pubbliche e pagine degli inserzionisti, non un ads manager
E-commerceTikTok Shop, Facebook Marketplace, AmazonProdotti, annunci e recensioni, non un backend per chi vende
MappeGoogle MapsLuoghi, ricerca e recensioni
App storeGoogle Play, Apple App StoreDettagli pubblici delle app, classifiche e recensioni
SEORisorse SEO per parole chiave e SERPRecord dei risultati di ricerca e delle parole chiave

La profondità conta comunque più del nome di una piattaforma. Instagram non è “un’unica API di Instagram”. TikTok Shop non è il catalogo dei video di TikTok. Consulta il catalogo API per gli input accettati e i campi restituiti da ogni risorsa.

REST è una sola porta d’ingresso. MCP, la CLI e l’Agent Skill sono altre porte d’ingresso allo stesso catalogo. Questo articolo resta sulla specifica HTTP.

Un unico schema di autenticazione e di attività

Tutti gli endpoint attuali del catalogo usano l’autenticazione Bearer:

Authorization: Bearer $SOCQ_API_KEY
Content-Type: application/json

La creazione di una risorsa segue una route prevedibile:

POST /v1/{platform}/{resource}

Esempi:

POST /v1/tiktok/profiles
POST /v1/instagram/reels
POST /v1/x/search
POST /v1/linkedin/jobs
POST /v1/tiktok-shop/search
POST /v1/facebook-ad-library/search
POST /v1/google-maps/search

Gli input restano specifici per risorsa. I profili possono accettare username, le entità note possono richiedere URL e gli endpoint di ricerca accettano query più i filtri supportati. Un’API unificata dovrebbe normalizzare il comportamento operativo senza forzare input non validi in un unico corpo generico.

Il flusso asincrono condiviso

Una raccolta di lunga durata non dovrebbe tenere aperta una connessione HTTP. SocQ crea un’attività:

Client
  └─ POST platform resource
       └─ task_id
            └─ poll common task endpoint
                 ├─ queued
                 ├─ running
                 ├─ succeeded → paginated records
                 └─ failed/cancelled → normalized error

Conserva l’ID attività prima di interrogarne lo stato. Usa un backoff esponenziale, considera normali gli stati queued e running, elabora i record solo dopo il completamento e continua quando il risultato indica altre pagine.

Questa macchina a stati condivisa permette a un solo worker di orchestrare l’intero catalogo:

def submit(platform, resource, payload):
    return post(f"/v1/{platform}/{resource}", json=payload)["data"]["task_id"]

def wait_for_task(task_id):
    while True:
        task = get(f"/v1/tasks/{task_id}")["data"]
        if task["status"] == "succeeded":
            return task
        if task["status"] in {"failed", "cancelled"}:
            raise CollectionError(task)
        backoff()

Il codice di produzione dovrebbe anche conservare i cursori, limitare i nuovi tentativi, classificare gli errori e rendere idempotenti le scritture a valle.

Un modello di record normalizzato

Dove applicabile, i record usano convenzioni comuni:

{
  "id": "source-id",
  "platform": "tiktok",
  "resource": "videos",
  "type": "video",
  "url": "https://source.example/item",
  "author": {
    "id": "author-id",
    "username": "creator",
    "name": "Creator"
  },
  "metrics": {
    "likes_count": 120,
    "comments_count": 8
  },
  "media": [],
  "created_at": "2026-09-09T08:00:00Z",
  "collected_at": "2026-09-10T08:00:00Z",
  "extra": {}
}

Non tutte le risorse hanno tutti i campi. Un profilo può esporre name, description e avatar_url; un post può usare text; un video può avere durata o audio; un’offerta di lavoro contiene dati contrattuali; un risultato di Shop contiene prezzo e contesto SKU in extra. Modella i campi facoltativi come nullable e ramifica in base a resource o type quando serve una logica specifica della fonte.

Cosa si può unificare

Autenticazione

Una sola chiave API di SocQ può autenticare le richieste su tutto il catalogo.

Ciclo di vita delle attività

Invio, interrogazione dello stato, stati finali, paginazione e osservabilità delle attività possono seguire un unico schema di worker.

Provenienza

Ogni record archiviato dovrebbe conservare platform, resource, URL di origine o query, orario di raccolta e ID dell’attività di origine.

Entità comuni

ID, URL, autori, metriche pubbliche, riferimenti ai contenuti multimediali, orari di pubblicazione e orari di raccolta possono seguire convenzioni condivise dove la fonte li espone.

Gestione degli errori

La tua applicazione può ricondurre validazione degli input, risorse pubbliche non disponibili, errori temporanei a monte, limiti di frequenza ed errori finali di raccolta a un’unica tassonomia interna.

Cosa non va forzato in un’unica forma

Le metriche non sono intercambiabili

Una riproduzione di TikTok, una visualizzazione di Instagram, una visualizzazione di YouTube, un’impression di X, un punteggio di Reddit, una reazione di LinkedIn, un’impression pubblicitaria, il numero di prodotti venduti e una valutazione su una mappa possono avere definizioni e disponibilità diverse. Conserva il nome originale della metrica invece di creare un unico numero di engagement fuorviante.

La profondità delle risorse varia

YouTube ha trascrizioni e canali. LinkedIn ha offerte di lavoro e aziende. Reddit ha i subreddit. TikTok ha gli hashtag. Le librerie degli annunci hanno le creatività. Le mappe hanno i luoghi. Una matrice di copertura dovrebbe mostrare queste differenze.

La semantica della scoperta varia

Posizionamento nelle ricerche, copertura storica, localizzazione, limiti dei risultati e freschezza cambiano da piattaforma a piattaforma. La stessa query su reti diverse – o su Shop, libreria degli annunci e mappe – non è una misura confrontabile alla pari.

Accesso e visibilità variano

Disponibilità pubblica, contenuti eliminati, account privati, restrizioni di età o di area geografica e viste con accesso effettuato sono specifici di ogni piattaforma. Un’API unificata non deve far credere che i controlli di accesso scompaiano.

Esempi di richieste nelle diverse categorie

Raccogliere i profili di TikTok:

curl -X POST "https://api.socq.ai/v1/tiktok/profiles" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["tiktok","natgeo"]}'

Cercare su TikTok Shop:

curl -X POST "https://api.socq.ai/v1/tiktok-shop/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"running shoes","results_limit":100,"region":"US"}'

Cercare nella Facebook Ad Library:

curl -X POST "https://api.socq.ai/v1/facebook-ad-library/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"running shoes","results_limit":100,"country":"US","status":"ACTIVE","media_type":"VIDEO","sort_by":"total_impressions"}'

Cercare su Google Maps:

curl -X POST "https://api.socq.ai/v1/google-maps/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"coffee","location":"New York, NY","country":"US","results_limit":3}'

L’autorizzazione e il flusso delle attività restano gli stessi; cambiano solo gli input validi per la risorsa. Tra le guide specifiche per piattaforma ci sono TikTok, X e SocQ MCP.

Schema di client TypeScript

Usa tipi di richiesta discriminati invece di un payload generico senza tipo:

type RequestMap = {
  "tiktok/profiles": { usernames: string[] };
  "instagram/reels": { usernames: string[]; results_limit?: number };
  "x/search": { query: string; results_limit?: number; sort_by?: "latest" | "top" };
  "linkedin/jobs": { urls: string[] };
  "tiktok-shop/search": { query: string; results_limit?: number; region?: string };
  "facebook-ad-library/search": { query: string; results_limit?: number; country?: string };
  "google-maps/search": { query: string; location: string; country?: string; results_limit?: number };
};

async function submit<K extends keyof RequestMap>(
  endpoint: K,
  payload: RequestMap[K],
) {
  const response = await fetch(`https://api.socq.ai/v1/${endpoint}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SOCQ_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) throw new Error(`SocQ ${response.status}`);
  return response.json();
}

Genera o mantieni questi tipi a partire da un registro interno degli endpoint, così documentazione, validazione e client non possono divergere in modo indipendente.

Progettazione del database

Un data warehouse pratico usa un involucro comune più tabelle per risorsa:

social_record
  platform
  resource
  source_id
  canonical_url
  author_id
  created_at
  collected_at
  source_task_id
  raw_json

social_metric_snapshot
  platform
  resource
  source_id
  collected_at
  metric_name
  metric_value

resource-specific tables
  transcript segments
  job details
  profile attributes
  product and listing fields
  place and review fields
  media metadata

Non mettere tutti i possibili campi delle piattaforme in un’unica tabella da 200 colonne. Conserva l’involucro normalizzato, poi usa tabelle tipizzate per risorsa o JSON validato per la profondità specifica della fonte.

Normalizzazione degli errori e nuovi tentativi

Distingui:

  • Input non valido che non riuscirà mai.
  • Risorse pubbliche non supportate o non disponibili.
  • Errori di autenticazione e di account.
  • Limiti di frequenza o di crediti.
  • Errori temporanei a monte.
  • Bug del fornitore o errori di validazione dello schema.

Riprova solo le classi di errori temporanei. Usa un backoff esponenziale limitato con jitter. Registra il tentativo e l’ID attività e rendi idempotenti gli upsert, così che un nuovo tentativo non possa duplicare i record.

API unificata e API native delle piattaforme

Fattore decisionaleAPI unificata per dati pubbliciAPI native delle piattaforme
IntegrazioneUn solo schema di autenticazione e di attivitàDiverso per ogni piattaforma
SchemaNucleo normalizzatoOggetti nativi della piattaforma
ManutenzioneIl fornitore assorbe gran parte dei cambiamenti delle fontiIl tuo team segue ogni piattaforma
Dati esterni pubbliciCopertura delle risorse supportateSpesso limitati da prodotto e permessi
Pubblicazione e azioni sugli accountNon previste da SocQServono le API ufficiali
Profondità specifica della piattaformaLimitata al catalogoMassima quando l’accesso è approvato
GovernanceUn fornitore più gli obblighi della fonteRapporto diretto con la piattaforma

Non è una scelta aut-aut. Usa le API native per le scritture, le analisi dei tuoi account e i flussi soggetti a permessi; usa un’API unificata per dati pubblici per le letture pubbliche supportate quando questo modello di accesso è adeguato.

Casi d’uso comuni

  • Monitoraggio di brand e argomenti sui social network.
  • Ricerca su influencer e creator.
  • Analisi dei contenuti e delle creatività della concorrenza.
  • Ricerca pubblica su Shop, Marketplace e prodotti.
  • Raccolta di luoghi e recensioni.
  • Dataset di app store e SEO.
  • Strumenti di ricerca per agenti AI che condividono un unico catalogo.
  • Dataset di commenti, post, video e trascrizioni.
  • Arricchimento di profili pubblici o aziende con adeguate tutele.

Progetta la pipeline attorno ai soli dati strettamente necessari per il caso d’uso, non attorno a tutti i campi che la fonte potrebbe esporre.

Quando non usare un’API unificata per dati pubblici

Non usare SocQ quando:

  • Devi pubblicare, rispondere, inviare DM o gestire annunci.
  • Ti servono le statistiche private di un account con l’autorizzazione dell’utente.
  • Un programma ufficiale per i partner è obbligatorio.
  • Una singola funzionalità specifica di una piattaforma è essenziale e manca dal catalogo.
  • I tuoi requisiti legali, contrattuali o di governance vietano la raccolta prevista.

La risposta giusta può essere un’API ufficiale, un fornitore di account collegati, un dataset con licenza o nessuna raccolta.

  1. Definisci un involucro interno normalizzato prima di aggiungere fonti.
  2. Integra una risorsa di alto valore e conserva le risposte grezze.
  3. Verifica ID, timestamp, metriche, contenuti multimediali e gestione dei valori nulli.
  4. Aggiungi una seconda piattaforma o categoria attraverso lo stesso worker di attività.
  5. Mantieni gli adattatori specifici per fonte al confine di validazione.
  6. Esegui in parallelo la vecchia e la nuova pipeline su un campione fisso.
  7. Confronta record unici accettati, freschezza e costo.
  8. Migra gradualmente e mantieni vie di ritorno.

Aggiungere piattaforme diventa un lavoro di configurazione solo quando significato dei dati, osservabilità e gestione dei guasti sono davvero standardizzati.

Sicurezza, privacy e uso responsabile

Conserva le chiavi API in un gestore di segreti, usa un accesso con privilegi minimi ai dati archiviati, cifra trasporto e archiviazione, registra gli accessi amministrativi e definisci procedure di conservazione e cancellazione.

Raccogli solo i dati pubblici supportati e necessari per uno scopo legittimo. Non aggirare account privati, barriere di accesso, controlli sul pubblico o altre restrizioni. Verifica le condizioni delle piattaforme, gli obblighi sulla privacy, le norme sulla proprietà intellettuale e la legge applicabile. Un’interfaccia tecnica unificata non unifica né elimina gli obblighi legali.

Domande frequenti (FAQ)

Un’API unificata per i social media sostituisce le API ufficiali?

No. SocQ gestisce le letture pubbliche supportate. Le API ufficiali restano necessarie per la pubblicazione, le azioni utente via OAuth, le statistiche private e i prodotti per i partner delle piattaforme.

Tutte le 27 piattaforme restituiscono esattamente gli stessi campi?

No. Condividono convenzioni normalizzate dove i concetti coincidono, mentre i campi specifici per risorsa restano distinti.

Mi serve una chiave API per ogni piattaforma?

Una sola chiave di SocQ copre il catalogo di SocQ. Le integrazioni ufficiali o di altri fornitori richiedono comunque le proprie credenziali.

SocQ può pubblicare post social?

No. Gli endpoint attuali sono operazioni di sola lettura su dati pubblici.

Come vengono gestiti i limiti di frequenza?

La tua applicazione dovrebbe rispettare i limiti dell’account SocQ, conservare lo stato delle attività asincrone, applicare un backoff durante l’interrogazione dello stato e riprovare solo gli errori temporanei.

È adatta agli agenti AI?

Sì, quando l’agente usa strumenti tipizzati, input vincolati, persistenza dello stato delle attività, validazione e approvazione umana per le azioni a valle con conseguenze importanti. Se il client parla quel protocollo, parti da MCP.

Cosa copre il catalogo attuale?

27 piattaforme e più di 170 endpoint tra social network, librerie degli annunci, e-commerce, mappe, app store e SEO. Consulta /apis per l’elenco aggiornato.

MULTI-PLATFORM API

Prova il flusso di lavoro con un URL pubblico di Multi-platform

Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.

Scopri le API di Multi-platform