API di supporto
Ogni endpoint di supporto: esempi cURL, Python e Node; paesi e stati supportati, sottocategorie e siti delle piattaforme di pubblicazione del tuo piano.
Gli endpoint di supporto sono i tre cataloghi di riferimento usati dal resto dell'API per la validazione: quali paesi e stati sono supportati, quali categorie di attività esistono e quali directory delle piattaforme di pubblicazione sono incluse nel tuo piano. Tutti e tre sono di sola lettura, senza paginazione e restituiscono l'insieme completo dei dati, quindi è sufficiente una chiave Read (lettura) e la memorizzazione nella cache conta più della paginazione.
Panoramica degli endpoint
Elenca paesi e stati supportati
GET /countries
Restituisce il catalogo completo sotto data.supportedCountries. Ogni paese contiene un codice ISO, un id in base64, un databaseId numerico, un array states le cui voci hanno ciascuna un proprio codice ISO e tre flag relativi all'indirizzo: hasCity (città obbligatoria), stateRequired (stato obbligatorio e verificato rispetto a states) e hasPostalCode (il paese utilizza i codici postali). Per un paese non suddiviso in stati viene restituito un array states vuoto.
Parametri
Questo endpoint non accetta parametri. Restituisce sempre l'insieme completo dei dati.
curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "supportedCountries": [ { "databaseId": 13, "hasCity": true, "id": "Q291bnRyeToxMw==", "iso": "AU", "name": "Australia", "states": [ { "countryId": 13, "id": "139", "iso": "VIC", "name": "Victoria" }, { "countryId": 13, "id": "142", "iso": "NSW", "name": "New South Wales" } ] }, { "databaseId": 17, "hasCity": true, "id": "Q291bnRyeToxNw==", "iso": "BE", "name": "Belgium", "states": [] } ] }}I due campi iso contengono i valori che ti servono. Il valore iso di un paese diventa countryIso nelle operazioni di creazione e aggiornamento, mentre il valore iso di uno stato diventa stateIso. Validando entrambi rispetto a questo elenco prima di un'operazione di scrittura, puoi trasformare un 400 lato server in un messaggio chiaro nel tuo modulo.
Elenca le sottocategorie
GET /sub-categories
Restituisce circa 6.000 record di categorie sotto data.subcategories in un unico array senza paginazione. È la ricerca che converte un tipo di attività che conosci come testo libero nell'id numerico richiesto da un'operazione di scrittura su una sede.
Parametri
Nessuno. Il catalogo completo viene restituito a ogni chiamata.
curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "subcategories": [ { "databaseId": 4589, "id": "U3ViQ2F0ZWdvcnk6NDU4OQ==", "key": "3d-printing-service", "name": "3D printing service", "primary": true } ] }}Ogni record contiene cinque campi e quello da usare dipende dalla sua destinazione.
Una sede accetta una categoria principale in subCategoryId e fino a nove categorie aggiuntive in additionalCategoryIds.
Elenca i siti del piano
GET /plan-sites
Restituisce sotto data.planSites tutte le directory delle piattaforme di pubblicazione incluse nel piano del tuo account. Questo è l'elenco autorevole degli id numerici dei siti e solo gli id presenti qui sono validi nelle altre parti dell'API.
Parametri
Nessuno. La risposta è limitata al piano del tuo account.
curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "planSites": [ { "id": 1, "name": "Google Maps", "url": "maps.google.com", "supportedCountries": ["US", "CA", "IN", "GB", "DE"], "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"] }, { "id": 184, "name": "Facebook", "url": "facebook.com", "supportedCountries": ["US", "CA", "IN", "GB", "DE"], "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"] } ] }}I due array di paesi rispondono a domande diverse. supportedCountries indica in quali paesi il sito accetta una scheda, quindi filtra in base al valore countryIso della tua sede prima di proporre una piattaforma di pubblicazione. hideAddressSupportedCountries indica in quali paesi il sito rispetta l'impostazione che nasconde l'indirizzo, necessaria per un'attività che opera in un'area di servizio. Entrambi gli array possono contenere cinquanta o più codici; l'esempio sopra è abbreviato.
Gli id dei siti sono stabili ed è utile conoscerli: 1 è Google Maps e 184 è Facebook, le due piattaforme di pubblicazione a cui si rivolge la maggior parte dei flussi di connessione.
Link di azione per le sedi
Non è un endpoint autonomo. I link di azione per le sedi sono i pulsanti di Google come Order online (ordina online), Reserve a table (prenota un tavolo) e Book an appointment (prenota un appuntamento), e la piattaforma li gestisce come un campo della sede anziché come una risorsa separata. Li imposti tramite l'array placeActionLinks in fase di creazione e aggiornamento e li recuperi da qualsiasi endpoint di lettura delle sedi.
Ogni voce richiede un placeActionType e un uri, prevede un flag isPreferred facoltativo con al massimo un link preferito per tipo e accetta un action pari a add o delete in fase di aggiornamento. I tipi validi, le regole di eliminazione e il comportamento di sincronizzazione sono tutti descritti in Link di azione per le sedi.
Errori che potresti riscontrare
Nessuno di questi endpoint esegue operazioni di scrittura, quindi l'uso di una chiave Read non restituisce mai SY90016 qui. L'elenco completo è in Codici di errore.
Passaggi successivi
- Consulta paesi e categorie: la guida operativa, con una spiegazione passo passo del passaggio alla creazione di una sede.
- Aggiungi una sede: dove vengono utilizzati
countryIsoesubCategoryId. - Trova e correggi gli errori delle schede: utilizza i siti del piano per distinguere una piattaforma di pubblicazione mancante da una che presenta errori.
- Riferimento delle API di supporto per l'elenco completo dei campi di tutti e tre gli endpoint.