POST/api/v4/locations/update

Aggiorna una sede

Aggiorna i campi scrivibili di una sede esistente. Vengono modificati solo i campi che invii.

Richiede una chiave API. Consulta Autenticazione per il formato dell’header e la rotazione delle chiavi.

Parametri

Corpo

Un campo annidato contrassegnato come obbligatorio si applica solo quando invii il campo padre. Se il padre è facoltativo e lo ometti, i suoi campi figli obbligatori non si applicano.

Nome	Tipo	Obbligatorio	Descrizione
input.id	string	obbligatorio	The location's Base64-encoded Relay ID to update.
input.name	string	facoltativo	Business name.
input.street	string	facoltativo	Street address.
input.city	string	facoltativo	City.
input.stateIso	string	facoltativo	State/region ISO code.
input.postalCode	string	facoltativo	Postal or ZIP code.
input.countryIso	string	facoltativo	Two-letter country ISO code.
input.phone	string	facoltativo	Primary phone number.
input.bizUrl	string	facoltativo	Business website URL. Published to directories as the location's website.
input.primaryGbpSiteCategoryId	string	facoltativo	Primary Google Business Profile category, as a GCID (e.g. `gcid:restaurant`). Resolved against `countryIso`, so send the two together.
input.additionalGbpSiteCategoryIds	array of strings	facoltativo	Additional Google Business Profile categories, as GCIDs. Also resolved against `countryIso`.
input.offeringsUrl	string	facoltativo	URL of the menu, catalogue, or service list.
input.bookingUrl	string	facoltativo	URL customers use to book an appointment.
input.reservationUrl	string	facoltativo	URL customers use to make a reservation.
input.street1	string	facoltativo	Second address line (suite, unit, floor).
input.latitude	string	facoltativo	Latitude of the location, as a string. Send with `longitude`; publishers use it when the address alone is ambiguous.
input.longitude	string	facoltativo	Longitude of the location, as a string. Send with `latitude`.
input.ownerEmail	string	facoltativo	Email of the location owner. Used for listing claims and verification, not for login.
input.ownerName	string	facoltativo	Name of the location owner.
input.facebookUrl	string	facoltativo	URL of the location's Facebook page.
input.twitterUrl	string	facoltativo	URL of the location's X (Twitter) profile.
input.linkedinUrl	string	facoltativo	URL of the location's LinkedIn page.
input.instagramUrl	string	facoltativo	URL of the location's Instagram profile.
input.youtubeUrl	string	facoltativo	URL of the location's YouTube channel.
input.tiktokUrl	string	facoltativo	URL of the location's TikTok profile.
input.pinterestUrl	string	facoltativo	URL of the location's Pinterest profile.
input.tagline	string	facoltativo	Short tagline for the business.
input.description	string	facoltativo	Business description. Published to Google Business Profile as the business description.
input.yearOfIncorporation	string	facoltativo	Year the business was incorporated, e.g. `2014`.
input.googleAdsPhone	string	facoltativo	Alternate phone shown on Google Ads location extensions instead of `phone`.
input.additionalPhones	array of strings	facoltativo	Secondary phone numbers submitted to Google Business Profile.
input.videos	array of strings	facoltativo	Video URLs for the location.
input.additionalCategoryIds	array of integers	facoltativo	Secondary Listings API subcategory IDs, from the subcategories endpoint. Distinct from `additionalGbpSiteCategoryIds`, which takes Google GCIDs.
input.subCategoryId	integer	facoltativo	Primary subcategory ID. Pick a valid ID from the subcategories list endpoint.
input.storeId	string	facoltativo	Unique store code. Must be unique across the account.
input.enabledSiteIds	array of integers	facoltativo	Site IDs to publish this location to, when you want a subset of your plan's sites. See the plan-sites endpoint for valid IDs. Omit to publish to every site in your plan.
input.updateOnlySiteIds	array of integers	facoltativo	Restrict this update to the given site IDs. Other sites keep their current published values.
input.contentPreferredLanguage	string	facoltativo	Preferred language for the location's published content, e.g. `ENGLISH`.
input.submissionDisabledSiteIds	array of integers	facoltativo	Site IDs to exclude from submission. The inverse of `enabledSiteIds`, useful when you want every site in your plan except a few.
input.hideAddress	boolean	facoltativo	Set `true` for a service-area business. ListingsAPI stores the address you send but does not submit it to publishers.
input.temporarilyClosed	boolean	facoltativo	Set `true` to stop publishing business hours while the location is temporarily closed.
input.serviceItems	array of objects	facoltativo	Services offered, published to Google Business Profile.
input.paymentMethods	array of strings	facoltativo	Payment methods accepted. One or more of `VISA`, `MASTERCARD`, `AMEX`, `CASH`, `CHEQUE`, `CRYPTO`, `DINERS_CLUB`, `DISCOVER`, `FINANCING`, `INVOICE`, `TRAVELERS_CHECK`, `APPLE_PAY`, `SAMSUNG_PAY`, `PAYPAL`, `ANDROID_PAY`.
input.businessHours	array of objects	facoltativo	Hours. Each entry is `{ day, type, slots }`, plus `specialDate` for a `SPECIAL` entry. Send the full seven-day week when you set hours.
input.businessHours[].day	string	obbligatorio	One of MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY, or SPECIAL (a one-off override for the date in `specialDate`).
input.businessHours[].type	string	obbligatorio	`OPEN` or `CLOSED`.
input.businessHours[].specialDate	string	facoltativo	Date of a one-off override, as `YYYY-MM-DD`. Set this only when `day` is `SPECIAL`.
input.businessHours[].slots	array of objects	facoltativo	Open intervals for the day, each `{ start, end }` (e.g. `09:00am`, `05:00pm`). Use an empty array when `type` is `CLOSED`.
input.businessHours[].slots[].start	string	obbligatorio	Opening time for the interval, e.g. `09:00am`.
input.businessHours[].slots[].end	string	obbligatorio	Closing time for the interval, e.g. `05:00pm`.
input.moreHours	array of objects	facoltativo	Additional hour sets (e.g. delivery, drive-through). Each entry is `{ hoursTypeId, moreHour }`, where `moreHour` is an array of `{ day, type, slots }` using the same shape as `businessHours` (minus `specialDate`).
input.serviceArea	object	facoltativo	Service-area business config: `businessType`, `regionCode`, and a `placeInfos` array of `{ placeId, placeName }`.
input.customAttributes	array of objects	facoltativo	Custom attribute values for the location. Each item is `{ slug, value }`, where `slug` identifies a custom attribute registered on your account and `value` is an array of strings. Sending a slug that is not registered returns `SY10035`. Registering a new custom attribute is not yet available through the API.
input.placeActionLinks	array of objects	facoltativo	Google action links (ordering, delivery, takeout, reservation, appointment). Each item: `placeActionType` (enum), `uri` (string), optional `isPreferred` (boolean), optional `action` (`add`, the default, or `delete`), optional `name` (the link identifier returned by read endpoints once synced to Google). Only the links you reference are affected; links you don't include are left unchanged. See the Place Action Links guide.

Richiesta di esempio

Corpo pronto da incollare. Sostituisci gli ID e i valori segnaposto con i tuoi.

Request body

{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "phone": "5125550199",    "bizUrl": "https://acmekitchen.example.com",    "primaryGbpSiteCategoryId": "gcid:restaurant",    "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": [] }    ]  }}

Risposte

200Location updated. `success` is true and the updated location summary is returned.

Response

{  "data": {    "updateLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "street": "600 Congress Ave, Suite 200",        "city": "Austin",        "stateIso": "TX",        "countryIso": "US",        "postalCode": "78701",        "phone": "5125550199",        "storeId": null,        "status": "APPROVED",        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

401Unauthenticated, missing or invalid API key.

Aggiorna una singola sede. Vengono modificati solo i campi presenti in input; tutti quelli che ometti mantengono il valore attuale. id è l'unico campo obbligatorio.

Caso d'uso: correggere un numero di telefono. Invia solo id e phone per correggere i recapiti senza modificare l'indirizzo o gli orari. La risposta restituisce la sede aggiornata, così puoi verificare che i nuovi valori siano stati applicati.

Caso d'uso: pubblicare un orario settimanale completo. Invia l'array businessHours con tutti e sette i giorni (come nella richiesta di esempio) per impostare gli intervalli di apertura per ciascun giorno. Contrassegna i giorni di chiusura con { "day": "SUNDAY", "type": "CLOSED", "slots": [] }.

Regole per gli orari di apertura.

Fornisci tutti e sette i giorni; una settimana incompleta viene rifiutata.
Gli orari utilizzano start/end all'interno di ogni voce slots (e.g, 09:00am, 05:00pm); gli intervalli di uno stesso giorno non devono sovrapporsi.
Le eccezioni per festività ed eventi sono voci aggiuntive con day: "SPECIAL" e un specialDate (YYYY-MM-DD), inviate insieme alle sette voci dei giorni della settimana, mai al loro posto.
Usa SPECIAL solo in businessHours. Le voci moreHours non hanno il campo specialDate, quindi un giorno SPECIAL al loro interno non contiene alcuna data.
Usa moreHours per gli orari secondari (consegna, servizio drive-through), identificati dalla chiave hoursTypeId.

Invia sempre l'intera settimana. Le piattaforme di pubblicazione si aspettano un orario completo MONDAY–SUNDAY; invia tutte e sette le voci ogni volta che imposti businessHours, usando type: "CLOSED" (con slots vuoto) per i giorni di chiusura anziché omettere il giorno.

Aspetti a cui prestare attenzione.

Il campo identificativo è id (l'ID Relay in Base64 restituito da ogni endpoint di lettura).
Se la validazione fallisce, la chiamata restituisce comunque HTTP 200 con success: false e un array errors popolato; controlla sempre success, non solo il codice di stato.

Link di azione della sede

placeActionLinks gestisce i pulsanti di azione di una sede su Google (ordini, consegna, asporto, prenotazioni, appuntamenti). Il modello di scrittura è append/upsert, non di sostituzione:

action: "add" (il valore predefinito): aggiunge un nuovo link oppure aggiorna direttamente uri/isPreferred di un link salvato.
action: "delete": rimuove un link salvato e mette in coda la sua rimozione da Google.
I link che non includi nella richiesta vengono lasciati invariati; omettere un link non lo rimuove mai.

Come viene individuato un link (per la modifica o l'eliminazione): tramite name, se presente, altrimenti tramite placeActionType + uri. Includi name (ottenuto da un endpoint di lettura) quando lo hai a disposizione, per una corrispondenza più precisa; un link che non è ancora stato sincronizzato con Google non ha name e viene individuato tramite placeActionType + uri.

Valori validi per placeActionType: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE. Al massimo un link preferito per tipo.

Modificare l'URL di un link = rimuovere quello vecchio + aggiungere quello nuovo nella stessa richiesta:

JSON

{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "placeActionLinks": [      { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com",     "name": "<link-name-if-synced>", "action": "delete" },      { "placeActionType": "FOOD_ORDERING", "uri": "https://new-order.example.com", "isPreferred": true, "action": "add" }    ]  }}

Subito dopo una scrittura, name e submissionStatus di un link sono null; vengono popolati quando il link viene sincronizzato con Google. Consulta la guida ai link di azione della sede per il flusso completo, incluso il modo in cui i link rilevati direttamente su Google compaiono sotto discoveredPlaceActionLinks.

Request

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",      "primaryGbpSiteCategoryId": "gcid:restaurant",      "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": []        }      ]    }  }'

Run in playground