Listings APIListings API
Accedi

Aggiorna i dettagli e gli orari di una sede

Modifica recapiti, pubblica orari settimanali completi con eccezioni per data, indica chiusure temporanee, imposta categorie Google e rileggi le modifiche.

POST /locations/update esegue un aggiornamento parziale. Tutti i campi vanno inseriti in input, input.id è l'unico campo obbligatorio e i campi che ometti mantengono i valori attuali. Ogni sezione seguente modifica solo il corpo JSON della richiesta.

1. Aggiorna il numero di telefono e il sito web

Invia id insieme ai campi da modificare. Le piattaforme di pubblicazione pubblicano bizUrl come URL del sito web. locations.update() del Python SDK accetta un dict con chiavi camelCase e updateLocation() del Node SDK accetta lo stesso oggetto.

Phone and website
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "phone": "5125550199",    "bizUrl": "https://acmekitchen.example.com"  }}'
JSON
{  "data": {    "updateLocation": {      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "phone": "5125550199",        "status": "APPROVED"      }    }  }}

Un errore di validazione restituisce comunque HTTP 200, con success: false e il motivo in data.updateLocation.errors, quindi controlla success anziché il codice di stato. In questo caso, entrambi gli SDK sollevano ValidationError.

2. Imposta gli orari settimanali

businessHours è un array con una voce per ogni giorno della settimana. Invia sempre tutti e sette i giorni e indica un giorno di chiusura con type: "CLOSED" e un array slots vuoto, anziché ometterlo. Gli intervalli all'interno di una giornata non devono sovrapporsi.

CampoValoriNote
dayDa MONDAY a SUNDAY, oppure SPECIALSPECIAL è un'eccezione valida solo per la data indicata in specialDate.
typeOPEN oppure CLOSEDUsa CLOSED con slots: [] per un giorno di chiusura.
slots[].start, slots[].end09:00am, 05:00pmOrari nel formato a 12 ore con am o pm. Sono consentite più fasce orarie al giorno per gli orari spezzati.
specialDateYYYY-MM-DDSolo in una voce SPECIAL, inviata insieme alle sette voci dei giorni della settimana, mai al loro posto.
moreHours[]hoursTypeId, moreHour[]Orari secondari, ad esempio per la consegna o il servizio drive-through. moreHour usa la stessa struttura con day, type e slots e non include specialDate.
Weekly hours
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "businessHours": [      { "day": "MONDAY",    "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "TUESDAY",   "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "THURSDAY",  "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "FRIDAY",    "type": "OPEN",   "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "SATURDAY",  "type": "OPEN",   "slots": [{ "start": "10:00am", "end": "02:00pm" }] },      { "day": "SUNDAY",    "type": "CLOSED", "slots": [] }    ]  }}'

Per una festività, aggiungi una voce SPECIAL alla fine dello stesso array. Sostituisce gli orari solo per quella data e lascia invariato il calendario settimanale:

JSON
{ "day": "SPECIAL", "type": "CLOSED", "specialDate": "2026-12-25", "slots": [] }

3. Indica una chiusura temporanea o nascondi l'indirizzo

temporarilyClosed: true indica che l'attività è chiusa e interrompe la pubblicazione dei suoi orari. Impostalo su false per riaprire. Per un'attività che opera in un'area di servizio, imposta hideAddress: true: ListingsAPI conserva l'indirizzo nei dati della sede, ma non lo invia alle piattaforme di pubblicazione.

Temporary closure
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "id": "TG9jYXRpb246MTgwMDI4OQ==", "temporarilyClosed": true } }'

4. Imposta le categorie Google

Google Business Profile ha una propria tassonomia delle categorie, separata dal valore numerico subCategoryId. primaryGbpSiteCategoryId accetta un GCID come gcid:restaurant e additionalGbpSiteCategoryIds ne accetta altri. Entrambi vengono risolti in base a countryIso, quindi invia il paese nella stessa chiamata.

Google categories
curl -X POST https://listingsapi.com/api/v4/locations/update \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "countryIso": "US",    "primaryGbpSiteCategoryId": "gcid:restaurant",    "additionalGbpSiteCategoryIds": ["gcid:pizza_restaurant", "gcid:italian_restaurant"]  }}'

Non confonderli con additionalCategoryIds, che accetta valori interi databaseId dall'endpoint delle sottocategorie. Consulta Consulta paesi, stati e categorie.

5. Rileggi i dati della sede

GET /locations-by-ids restituisce il record completo per uno o più ID in base64, passati come array JSON nel parametro di query ids. Confronta phone, businessHours e temporarilyClosed con i valori che hai inviato.

Verify
curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ=="]' \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getLocationsByIds": [      {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "phone": "5125550199",        "hideAddress": false,        "temporarilyClosed": true      }    ]  }}

Gli ID che non esistono nel tuo account vengono esclusi dall'array senza generare errori, quindi confronta il numero di risultati restituiti con quello richiesto.

Se i webhook sono configurati, viene generato un evento profile.updated. Un meccanismo di debounce limita l'invio a una volta per sede ogni 60 secondi, all'inizio dell'intervallo: le modifiche successive in quell'intervallo vengono accorpate e changed_fields descrive solo la modifica che lo ha avviato. Rileggi i dati della sede quando arriva l'evento e di nuovo dopo la chiusura dell'intervallo.

Passaggi successivi