Questo tutorial mostra come creare e modificare i dati sulla posizione. L'API My Business Business Information consente di:
- Crea una nuova sede.
- Eliminare una sede.
- Ottieni una località in base al nome della risorsa.
- Elenca tutte le sedi 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 su Ricerca e 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 maggiori dettagli su come iniziare a utilizzare l'API My Business Business Information, consulta Configurazione di base.
Crea una posizione
Puoi utilizzare l'API My Business Business Information per creare una nuova sede per un'attività con accounts.locations.create.
Per creare una sede, 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"
}
}
}
Eliminare una località
Puoi utilizzare l'API My Business Business Information per eliminare una sede con locations.delete.
Per eliminare una posizione, utilizza la seguente istruzione:
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Trova un luogo indicando il nome
Se hai molte attività associate al tuo account, potresti voler creare una sola sede. Puoi filtrare in base al nome dell'attività per ottenere una località specifica con locations.get.
Per ottenere un luogo in base al nome, utilizza il comando seguente. È necessario specificare una readMask per recuperare campi specifici. :
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
Restituire la versione di Google Maps
Per restituire la versione Google Maps di un luogo, aggiungi
googleUpdated all'URL della richiesta, come nell'esempio seguente:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
Se non viene restituito alcun risultato, viene restituito un codice di stato HTTP 404 NOT FOUND. Ulteriori dettagli sulla gestione degli aggiornamenti Google sono disponibili qui.
Elenco località
Quando gestisci una o più sedi, ti consigliamo di elencare tutte le sedi associate al tuo account. Utilizza l'API accounts.locations.list per elencare tutte le località associate a un utente.
Per elencare tutte le sedi direttamente di proprietà di o gestite 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 in modo da includere le
schede di proprietà indirettamente (di proprietà o gestite tramite un gruppo):
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}
Filtra i risultati quando elenchi le località
Puoi utilizzare i filtri per limitare i risultati che vengono restituiti quando chiami accounts.locations.list. Per filtrare una richiesta, aggiungi un'espressione di filtro all'URL di base, come mostrato in questo esempio:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22
Sintassi delle query di base
Una restrizione ha la seguente sintassi:
<field><operator><value>,
in cui 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 indicato, tutti i confronti sono confronti tra token senza distinzione tra maiuscole e minuscole. Ad esempio, "4 unità" corrisponde a "4, Privet Drive".
Combinare più campi in una query di filtro
L'API consente di connettere tutte le limitazioni dei campi con l'operatore AND. Tuttavia, per 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 relative a "ristorante_francese" o "ristorante_europeo" e l'etichetta "nuova apertura".
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}
Per filtrare le località entro 1000 chilometri da Boulder, Colorado (USA):
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 filtro supportati
Di seguito è riportato un elenco completo di tutti i campi che possono essere utilizzati per i filtri:
| Campi | Descrizione ed esempio |
|---|---|
| Campi di corrispondenza delle stringhe | |
title |
Il nome reale dell'azienda
|
categories |
La combinazione della categoria principale e delle categorie aggiuntive. Tieni presente che "gcid:" deve essere omesso. Se sono presenti più categorie, questo filtro trova una corrispondenza se almeno una categoria corrisponde a questo pattern.
|
phone_numbers.primary_phone |
Il numero di telefono principale in formato E.164 (ad esempio: "+441234567890").
|
storefront_address.region_code |
Il codice regione CLDR del paese/della regione dell'indirizzo
|
storefront_address.administrative_area |
La suddivisione amministrativa più elevata utilizzata per gli indirizzi postali di un paese o di una regione
|
storefront_address.locality |
La parte relativa a città/paese dell'indirizzo
|
storefront_address.postal_code |
Il codice postale dell'indirizzo.
|
metadata.place_id |
Se questa sede è stata verificata ed è collegata a/visualizzata su Google Maps, questo campo corrisponde all'ID luogo della sede
|
openInfo.status |
Indica se la sede è attualmente aperta al pubblico (
|
labels |
Una raccolta di stringhe in formato libero che ti consente di taggare la tua attività. A differenza di tutti gli altri campi, questo valore deve corrispondere esattamente a un'etichetta completa che includa lettere maiuscole e minuscole e non solo a un token. Ad esempio, se un'etichetta è "XX YY", né "XX" né "xx yy" corrisponderanno.
|
storeCode |
Identificatore esterno per questa sede, che deve essere univoco all'interno di un determinato account
|
| Funzioni | |
distance |
Consente di filtrare in base alla distanza della posizione da un punto geografico.
|
Ordina per campo query
Puoi ordinare i risultati per nome dell'attività o 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
Applica patch a una località
Utilizza l'API My Business Business Information per aggiornare uno o più campi per una sede con locations.patch.
Per modificare uno o più campi di una località, utilizza la seguente istruzione:
Aggiungi i campi e i valori aggiornati con il campo della località e utilizza un elenco separato da virgole di campi aggiornati come valore per fieldMask.
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}