Listings APIListings API
Accedi

Esegui la tua prima chiamata API

Autenticati, elenca le tue sedi, esamina la struttura della risposta, scorri le pagine dei risultati e scopri come funzionano gli ID.

Questa guida presuppone che tu abbia un account e una chiave API ottenuti seguendo Primi passi. Ogni richiesta viene eseguita sull'API di produzione all'indirizzo https://listingsapi.com, quindi una chiamata di scrittura con una normale chiave API modifica dati reali. Per provare l'API senza intervenire sulle piattaforme di pubblicazione reali, usa il pass giornaliero gratuito per la sandbox.

1. Imposta la tua chiave API

Copia la chiave da Chiavi API nella dashboard ed esportala una sola volta nella tua shell:

bash
export LISTINGSAPI_KEY="your-api-key"

Ogni chiave ha un livello di accesso. Una chiave Read (lettura) consente tutte le consultazioni e tutti i report descritti in queste guide. Per creare o aggiornare qualsiasi elemento, rispondere a una recensione o pubblicare un post serve una chiave Write (scrittura). Se invii una chiave Read a un endpoint di scrittura, l'endpoint restituisce lo stato HTTP 400 con il codice di errore SY90016.

2. Elenca le tue sedi

Gli altri endpoint fanno riferimento a una sede tramite il suo ID, quindi inizia elencando le sedi che hai. L'header REST Authorization usa lo schema API, seguito da uno spazio e dalla tua chiave API: Authorization: API <YOUR_API_KEY>.

List locations
curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY"

3. Leggi la risposta

L'API REST restituisce una risposta annidata anziché un semplice array. Il nome dell'operazione si trova sotto data, i risultati degli elenchi vengono restituiti come una connessione di edges e ogni edge contiene un node:

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "approved": "APPROVED",            "subCategoryName": "Restaurants"          }        }      ],      "pageInfo": {        "hasNextPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ=="      }    }  }}

Il Python SDK restituisce una pagina iterabile di oggetti. Il Node SDK restituisce locations e pageInfo. Quando chiami direttamente l'API REST, leggi data.allLocations.edges[].node.

4. Scorri le pagine dei risultati

Gli endpoint che elencano sedi e recensioni usano la paginazione a cursore. Richiedi una pagina con first, poi passa pageInfo.endCursor come after per recuperare la pagina successiva. Gli SDK possono leggere tutte le pagine per te.

Next page
curl "https://listingsapi.com/api/v4/locations?first=50&after=TG9jYXRpb246MTgwMDI4OQ==" \-H "Authorization: API $LISTINGSAPI_KEY"

Non tutti gli endpoint usano questo tipo di paginazione. Gli account collegati, i riepiloghi dei duplicati e i post usano page e perPage con un array records. Ogni guida indica il formato di paginazione usato dai suoi endpoint.

5. Due tipi di ID

Ogni record ha due identificatori. id è una stringa base64 come TG9jYXRpb246MTgwMDI4OQ==, che una volta decodificata diventa Location:1800289. databaseId è il semplice numero, 1800289.

Memorizza id in base64. Ogni endpoint di scrittura richiede ID codificati in base64, e questi sono i valori restituiti nei payload dei webhook. Molti endpoint di lettura che ricevono una sede nel percorso accettano anche il numero non codificato, ed entrambi gli SDK accettano entrambe le forme ed eseguono la codifica per te.

6. Errori e limiti di frequenza

Le risposte alle richieste non riuscite restituiscono lo stato HTTP corrispondente con un array errors. Il messaggio è preceduto da un codice di errore SY, elencato in Codici di errore:

JSON
{  "data": { "allLocations": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

I limiti di frequenza dipendono dal piano e le richieste vengono conteggiate al minuto, all'ora e al giorno. Launch consente 10 richieste al minuto. Quando superi un limite, l'API restituisce 429 con un header Retry-After; attendi il numero di secondi indicato prima di riprovare. Gli SDK sollevano RateLimitError e rendono disponibile lo stesso valore. Tutti i dettagli sono in Limiti di frequenza.

Passaggi successivi