POST/api/v4/locations

Crea una sede

Crea una nuova sede aziendale nel tuo account e la mette in coda per l'invio delle schede.

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.name	string	obbligatorio	Name of the business.
input.description	string	obbligatorio	Business description, minimum 200 characters (`SY10005` when missing or shorter). Publishers use it as the primary listing copy.
input.storeId	string	facoltativo	Unique store code. Must be unique across the account.
input.street	string	obbligatorio	Street address, 5 to 100 characters (`SY10011`).
input.city	string	obbligatorio	City. Required where the country's `hasCity` is `true` (`SY10126`). Where it is `false`, a city you send is dropped.
input.stateIso	string	obbligatorio	State ISO code. Required where the country's `stateRequired` is `true`, and must be one of that country's `states` (`SY10010`). Leave it out where `stateRequired` is `false`. See the countries and states endpoint for valid values.
input.postalCode	string	facoltativo	Postal code. Optional, but send it wherever the country's `hasPostalCode` is `true`. A value you send must match the country's format (`SY10014`).
input.countryIso	string	obbligatorio	Country ISO code. Must be a supported country (`SY10036`). See the countries and states endpoint for valid values.
input.phone	string	obbligatorio	Primary phone number, validated for the country (`SY10015`).
input.subCategoryId	integer	obbligatorio	Primary subcategory ID. Pick a valid ID from the subcategories list endpoint.
input.bizUrl	string	obbligatorio	Business website URL. Published to directories as the location's website. Some publishers refuse a listing without one.
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.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.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.customAttributes	array of objects	facoltativo	Publisher-specific attributes for the location.
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	Opening hours. Each entry is `{ day, type, slots }`, plus `specialDate` for a `SPECIAL` entry: `day` is an uppercase weekday enum (MONDAY–SUNDAY) or `SPECIAL`, `type` is `OPEN` or `CLOSED`, and `slots` is an array of `{ start, end }` time strings (e.g. `09:00am`, `05:00pm`). For a closed day use `type: "CLOSED"` with an empty `slots` array.
input.businessHours[].day	string	obbligatorio	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 }`. Omit or leave empty when `type` is `CLOSED`.
input.businessHours[].slots[].start	string	obbligatorio	Opening time, e.g. `09:00am`.
input.businessHours[].slots[].end	string	obbligatorio	Closing time, e.g. `05:00pm`.
input.serviceArea	object	facoltativo	Service-area definition for service-area businesses: `{ businessType, regionCode, placeInfos: [{ placeId, placeName }] }`.
input.placeActionLinks	array of objects	facoltativo	Google action links (ordering, delivery, takeout, reservation, appointment). Each item: `placeActionType` (enum), `uri` (string), optional `isPreferred` (boolean). On create every link is new, so no `action` is needed. See the Place Action Links guide.
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.clientMutationId	string	facoltativo	Optional correlation token returned unchanged in the response. It does not prevent duplicate writes: the server does not detect repeated calls that reuse the same value.

Richiesta di esempio

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

Request body

{  "input": {    "name": "Acme Kitchen",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby growers. Our dining room seats forty, takeout and delivery run until close, and the bar pours regional wine and beer on tap.",    "storeId": "ACME01",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "primaryGbpSiteCategoryId": "gcid:restaurant",    "additionalGbpSiteCategoryIds": ["gcid:pizza_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": [] }    ],    "placeActionLinks": [      { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true },      { "placeActionType": "FOOD_TAKEOUT", "uri": "https://takeout.acmekitchen.example.com" }    ]  }}

Risposte

200Location created successfully. Returns the new location as a summary object.

Response

{  "data": {    "createLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME01",        "name": "Acme Kitchen",        "street": "123 Jump Street",        "city": "New York",        "stateIso": "NY",        "postalCode": "10013",        "countryIso": "US",        "phone": "6443859313",        "status": "PENDING",        "primaryGbpSiteCategoryId": null,        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true, "name": null, "submissionStatus": null },          { "placeActionType": "FOOD_TAKEOUT", "uri": "https://takeout.acmekitchen.example.com", "isPreferred": false, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

400Bad request, validation failure (see `errors[]`).

401Unauthenticated, missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.

Crea una nuova sede aziendale. In caso di successo, la sede viene messa in coda per l'invio a tutte le piattaforme di pubblicazione incluse nel suo piano (oppure, se viene fornito enabledSiteIds, solo ai siti indicati). Campi obbligatori: name, un valore di description di almeno 200 caratteri, subCategoryId, countryIso e, per i paesi il cui sistema di indirizzamento prevede l'indicazione della città, city. Per poter essere effettivamente pubblicata, una sede deve anche avere un indirizzo e un numero di telefono validi; forniscili al momento della creazione per evitare un successivo aggiornamento.

Il valore id restituito è codificato in base64 (e.g. TG9jYXRpb246MTgwMDI5MA==); decodificalo per ottenere la forma interna Location:<databaseId>. Ogni chiamata successiva fa riferimento a questo id in base64.

Caso d'uso: aggiungere un singolo punto vendita con i relativi orari. Invia l'indirizzo, phone, subCategoryId e un array businessHours, con una voce per ogni giorno della settimana contenente le fasce type: "OPEN" e { start, end }, oppure type: "CLOSED" con un array slots vuoto per i giorni di chiusura. Memorizza la tua chiave in storeId per poter recuperare in seguito la sede tramite recupera tramite codici negozio senza dover tenere traccia dell'ID di Listings API.

Gli orari speciali richiedono gli orari regolari. Gli orari speciali (eccezioni per festività o eventi, inviate come voci businessHours con day: "SPECIAL", type: "OPEN" o "CLOSED" e un valore specialDate nel formato YYYY-MM-DD) vengono pubblicati solo quando la sede include anche il suo orario regolare MONDAY–SUNDAY; Google rifiuta una sede inviata con orari speciali ma senza orari regolari. Includi sempre tutti e sette i giorni della settimana in businessHours ogni volta che imposti voci SPECIAL; consulta le regole sugli orari dell'endpoint di aggiornamento per il modello completo.

Caso d'uso: pubblicare su un sottoinsieme di siti. Passa enabledSiteIds (gli ID dei siti ottenuti dall'endpoint plan-sites) per pubblicare la sede su un sottoinsieme selezionato di directory anziché su tutti i siti del piano, secondo il modello usato dalle agenzie per vendere una copertura dei siti articolata su più livelli.

Imposta i pulsanti di azione di Google al momento della creazione. Passa placeActionLinks per impostare i pulsanti di azione di Google della sede (prenotare un appuntamento, ordinare online e così via) nella stessa chiamata. I valori validi per placeActionType sono APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT e SHOP_ONLINE, con al massimo un link preferito per tipo. Subito dopo la creazione, name e submissionStatus di ciascun link hanno il valore null fino alla sincronizzazione del link con Google. Per aggiungere, modificare o rimuovere link in seguito, usa aggiorna una sede; consulta la guida ai link di azione dei luoghi per il modello completo.

Errori comuni (restituiti come 400 con i dettagli in errors[]): description deve contenere almeno 200 caratteri (SY10005), countryIso deve essere un paese supportato (SY10036), city è obbligatorio per i paesi il cui sistema di indirizzamento prevede l'indicazione della città (SY10126), state deve essere un codice ISO valido, il codice postale e il numero di telefono devono essere validi per il paese, subCategoryId deve esistere e storeId deve essere univoco all'interno dell'account. Ogni richiesta incide allo stesso modo sul tuo limite di frequenza indipendentemente dall'endpoint, quindi l'aggiunta di un numero elevato di sedi causa un 429 per il solo numero di richieste; rispetta l'header Retry-After e crea le sedi in sequenza anziché inviare le richieste in rapida successione.

Request

curl -X POST 'https://listingsapi.com/api/v4/locations' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "name": "Acme Kitchen",      "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby growers. Our dining room seats forty, takeout and delivery run until close, and the bar pours regional wine and beer on tap.",      "storeId": "ACME01",      "street": "123 Jump Street",      "city": "New York",      "stateIso": "NY",      "postalCode": "10013",      "countryIso": "US",      "phone": "6443859313",      "bizUrl": "https://acmekitchen.example.com",      "subCategoryId": 1432,      "primaryGbpSiteCategoryId": "gcid:restaurant",      "additionalGbpSiteCategoryIds": [        "gcid:pizza_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": []        }      ],      "placeActionLinks": [        {          "placeActionType": "FOOD_ORDERING",          "uri": "https://order.acmekitchen.example.com",          "isPreferred": true        },        {          "placeActionType": "FOOD_TAKEOUT",          "uri": "https://takeout.acmekitchen.example.com"        }      ]    }  }'

Run in playground