Consulta paesi, stati e categorie

Prima di creare una sede, trova paesi e codici stato supportati, l'ID numerico della categoria di attività e le piattaforme di pubblicazione del tuo piano.

La creazione di una sede richiede tre valori che devono provenire dall'API: un countryIso e un stateIso accettati dall'API, un subCategoryId numerico e, se vuoi limitare le piattaforme di pubblicazione, gli id dei siti inclusi nel tuo piano. Tre endpoint di catalogo forniscono questi valori. Tutti e tre restituiscono un semplice array senza paginazione.

1. Elenca i paesi e i codici degli stati

GET /countries restituisce tutti i paesi supportati, ciascuno con il proprio codice ISO, un flag hasCity e un array states. I valori iso vengono usati per countryIso e stateIso durante la creazione e l'aggiornamento. Il Python SDK espone questa funzionalità come client.countries() e il Node SDK come client.fetchCountries().

Countries

curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "iso": "AU",        "name": "Australia",        "hasCity": true,        "states": [          { "id": "139", "iso": "VIC", "name": "Victoria" },          { "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "iso": "BE",        "name": "Belgium",        "hasCity": true,        "states": []      }    ]  }}

hasCity: true indica che city è obbligatorio durante la creazione; con false, la città che invii viene scartata. stateRequired: true indica che stateIso è obbligatorio e deve essere uno dei states del paese; con false, omettilo. hasPostalCode: true indica che il paese utilizza i codici postali, quindi invia postalCode insieme all'indirizzo. La documentazione dell'endpoint dei paesi spiega ogni flag.

2. Trova l'id di una categoria

GET /sub-categories restituisce il catalogo completo delle categorie. Il valore da inviare come subCategoryId è databaseId, il numero intero, non id in base64. La categoria Restaurants, ad esempio, è 1432. Filtra l'elenco per nome nel tuo codice; non esiste un parametro di ricerca lato server.

Find a category

curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.subcategories[] | select(.name | test("restaurant"; "i")) | {databaseId, name, primary}'

JSON

{  "data": {    "subcategories": [      {        "databaseId": 1432,        "id": "U3ViQ2F0ZWdvcnk6MTQzMg==",        "key": "restaurants",        "name": "Restaurants",        "primary": true      }    ]  }}

Campo	A cosa serve
`databaseId`	Il numero intero da inviare come `subCategoryId`, oppure all'interno di `additionalCategoryIds` per un massimo di 9 categorie secondarie.
`name`	L'etichetta leggibile da mostrare in un selettore e da usare per trovare le corrispondenze.
`key`	Uno slug del nome adatto agli URL, che rimane stabile anche quando il nome cambia.
`primary`	Indica se la categoria può essere la sottocategoria principale di una sede. Scegli solo voci `true` per `subCategoryId`.

3. Verifica quali piattaforme di pubblicazione sono incluse nel tuo piano

GET /plan-sites elenca tutte le piattaforme di pubblicazione incluse nel tuo piano, ciascuna con un id numerico, un url, i paesi che accetta e i paesi in cui rispetta hideAddress. Questi id sono gli unici valori validi per enabledSiteIds durante la creazione e per submissionDisabledSiteIds durante l'aggiornamento. Filtra in base al paese della sede, in modo da proporre solo piattaforme di pubblicazione che la accetteranno.

Plan sites

curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.planSites[] | select(.supportedCountries | index("US")) | {id, name, url}'

JSON

{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 2,        "name": "Yelp",        "url": "yelp.com",        "supportedCountries": ["US", "CA", "GB", "DE", "FR"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "GB"]      }    ]  }}

Qui entrambi gli array dei paesi sono troncati; la risposta effettiva può elencare 50 o più codici per sito. Per un'attività con area di servizio, controlla anche hideAddressSupportedCountries, poiché una piattaforma di pubblicazione che accetta il paese potrebbe comunque rifiutare una scheda priva di indirizzo stradale.

4. Memorizza questi dati di consultazione nella cache

Tutti e tre i cataloghi cambiano raramente e nessuno utilizza la paginazione, quindi recupera ciascuno una sola volta all'avvio, conservalo in memoria o in una piccola tabella e aggiornalo a intervalli programmati. Chiamare questi endpoint durante ogni operazione di creazione consuma la quota di richieste senza restituire nuovi dati; nel piano Launch equivale a 3 delle 10 richieste al minuto a tua disposizione.

Catalogo	Dimensioni	Quando aggiornare
Paesi	Decine di paesi, centinaia di stati	Raramente. Un aggiornamento al giorno è più che sufficiente.
Sottocategorie	Circa 6.000 voci	Ogni giorno, oppure quando una creazione non riesce a causa di un `subCategoryId` sconosciuto.
Siti inclusi nel piano	Decine di piattaforme di pubblicazione	Quando cambi piano, poiché l'elenco è limitato al tuo piano.

Crea una mappa da name in minuscolo a databaseId per le sottocategorie e una mappa da countryIso a states per i paesi. Convalida l'indirizzo usando la cache prima di chiamare create, in modo che la tua applicazione rilevi un countryIso non supportato (SY10036) o un city mancante (SY10126) prima dell'invio della richiesta.

Passaggi successivi

Aggiungi una sede: usa subCategoryId, countryIso e gli ID dei siti che hai appena cercato.
Aggiorna una sede: modifica le categorie o escludi le piattaforme di pubblicazione con submissionDisabledSiteIds.
Elenca i paesi e gli stati supportati, Elenca le sottocategorie ed Elenca i siti del piano: le pagine di riferimento.