Utilizzare i dati sulla posizione

Questo tutorial mostra come creare e modificare i dati sulla posizione. L'API My Business Business Information ti consente di:

• Crea una nuova località.
• Elimina una località.
• Recupera una località in base al nome della risorsa.
• Elenca tutte le località di un account.
• Aggiorna uno o più campi per una sede.

Le sedi possono essere utilizzate in Google Ads, ma devono essere verificate per essere idonee alla visualizzazione nella Ricerca e su Maps. I dati sulla posizione sono rappresentati dalla raccolta accounts.locations.

Prima di iniziare

Prima di utilizzare l'API My Business Business Information, devi registrare la tua applicazione e ottenere le credenziali OAuth 2.0. Per informazioni dettagliate su come iniziare a utilizzare l'API My Business Business Information, consulta Configurazione di base.

Crea una località

Puoi utilizzare l'API My Business Business Information per creare una nuova sede per un'attività con accounts.locations.create.

Per creare una località, utilizza quanto segue:

POST
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?requestId=requestId&validateOnly=True|False

{
    "storeCode": "GOOG-SYD",
    "languageCode": "en-AU",
    "title": "Google Sydney",
    "phoneNumbers": {
      "primaryPhone": "02 9374 4000"
     },
    "storefrontAddress": {
      "addressLines": [
        "Level 5",
        "48 Pirrama Road"
      ],
      "locality": "Pyrmont",
      "postalCode": "2009",
      "administrativeArea": "NSW",
      "regionCode": "AU"
    },
    "websiteUri": "https://www.google.com.au/",
    "regularHours": {
      "periods": [
        {
          "openDay": "MONDAY",
          "closeDay": "MONDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "TUESDAY",
          "closeDay": "TUESDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "WEDNESDAY",
          "closeDay": "WEDNESDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "THURSDAY",
          "closeDay": "THURSDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "FRIDAY",
          "closeDay": "FRIDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        }
      ]
    },
    "categories": {
      "primaryCategory": {
        "name": "gcid:software_company"
      }
     }
}

Elimina una località

Puoi utilizzare l'API My Business Business Information per eliminare una sede con locations.delete.

Per eliminare una località, utilizza quanto segue:

DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}

Recupera una località in base al nome

Se al tuo account sono associate molte attività, potresti voler recuperare una singola sede. Puoi filtrare in base al nome dell'attività per ottenere una sede specifica con locations.get.

Per ottenere una località in base al nome, utilizza il seguente comando. Devi specificare un readMask per recuperare campi specifici. :

GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}

Restituisci la versione di Google Maps

GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}

Se non sono presenti risultati, viene restituito un codice di stato HTTP 404 NOT FOUND. Per maggiori dettagli sulla gestione degli aggiornamenti Google, consulta Accetta o rifiuta gli aggiornamenti.

Restituisci i dati sulla posizione estesi e modifica lo stato (v1alpha)

Per recuperare i dati sulla posizione forniti dal commerciante e quelli rivolti ai consumatori, insieme alle fasi del ciclo di vita delle modifiche per campo (ad esempio EDIT_LIFECYCLE_STAGE_PENDING o EDIT_LIFECYCLE_STAGE_REJECTED), all'origine della modifica (SOURCE_API o SOURCE_UI) e ai motivi della violazione delle norme in un'unica chiamata, utilizza locations.getExtended in v1alpha:

GET
https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}:getExtended

Per esempi di risposte complete e dettagli sull'interpretazione dello stato di modifica per campo e delle violazioni delle norme, consulta Controlla lo stato di modifica per località e attributi.

Elenco località

Quando gestisci una o più sedi, potresti voler elencare tutte le sedi associate al tuo account. Utilizza l'API accounts.locations.list per elencare tutte le sedi associate a un utente.

Per elencare tutte le sedi di proprietà o gestite direttamente da un utente autenticato, utilizza quanto segue:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}

Utilizza un carattere jolly '-' per l'account nell'URL della richiesta per includere le schede di proprietà indiretta (di proprietà o gestite tramite un gruppo):

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}

Filtra i risultati quando elenchi le località

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22

Sintassi delle query di base

Una limitazione ha la seguente sintassi: <field><operator><value>, dove l'operatore è EQUALS (=) o HAS (:). Gli operatori EQUALS (=) e HAS (:) sono equivalenti per tutti i campi tranne locationName (vedi la tabella di seguito).

Le virgolette sono codificate come "%22" e gli spazi come segni più (+).

Se non diversamente specificato, tutti i confronti sono confronti di token senza distinzione tra maiuscole e minuscole. Ad esempio, "4 drive" corrisponderà a "4, Privet Drive".

Combina più campi in una query di filtro

L'API consente di utilizzare AND per collegare tutte le limitazioni dei campi. Tuttavia, per quanto riguarda la parola chiave OR, tutte le limitazioni devono essere applicate allo stesso campo. Ad esempio, locationName=A OR labels=B non è consentito.

Esempio

L'esempio seguente mostra un'espressione di filtro che restituisce tutte le località con il nome "Pepé Le Pew". Mostra le categorie "french_restaurant" o "european_restaurant" e l'etichetta "newly open".

locationName=%22Pepé+Le+Pew%22+AND+
(categories=%22french_restaurant%22+OR+
categories=%22european_restaurant%22)+AND+
labels=%22newly+open%22

Cerca per distanza o account

L'esempio seguente mostra come cercare località entro una determinata distanza da un punto geografico:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(40.01, -105.27))<1000.0

Elenco di tutti i campi di filtro supportati

Di seguito è riportato un elenco esaustivo di tutti i campi che possono essere utilizzati per il filtro:

Ordina per campo di query

Puoi ordinare i risultati in base al nome dell'attività o al codice negozio, in ordine crescente o decrescente. Più criteri di ordinamento sono separati da virgole nella stringa orderBy, come nell'esempio seguente:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode

Aggiorna una località

Utilizza l'API My Business Business Information per aggiornare uno o più campi di una sede con locations.patch.

Per modificare uno o più campi di una sede, utilizza quanto segue:

PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
    "title": "Google Shoes"
}