Questo tutorial illustra come creare e modificare i dati sulla posizione. L'API My Business Business Information ti consente di eseguire le seguenti operazioni:
- Creare una nuova sede.
- Eliminare una sede.
- Ottenere una sede in base al nome della risorsa.
- Elencare tutte le sedi di un account.
- Aggiornare uno o più campi di una sede.
Le sedi possono essere utilizzate negli annunci, ma devono essere verificate per poter essere visualizzate nella Ricerca e su Maps. I dati sulla sede sono rappresentati dalla 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 la sezione Configurazione di base.
Creare una sede
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 sede
Puoi utilizzare l'API My Business Business Information per eliminare una sede con locations.delete.
Per eliminare una sede, utilizza quanto segue:
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Ottenere una sede in base al nome
Se al tuo account sono associate molte attività, potresti voler ottenere una singola sede. Puoi filtrare in base al nome dell'attività per ottenere una sede specifica con locations.get.
Per ottenere una sede in base al nome, utilizza quanto segue. Devi specificare un 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 di Google Maps di una sede, aggiungi
googleUpdated all'URL della richiesta, come nel seguente esempio:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
Se non ci sono risultati, viene restituito il codice di stato HTTP 404 NOT FOUND. Per maggiori dettagli sulla gestione degli aggiornamenti di Google, consulta
Accettare o rifiutare gli aggiornamenti.
Elencare le sedi
Quando gestisci una o più sedi, potresti voler elencare tutte le sedi associate al tuo account. Utilizza l' accounts.locations.list per elencare tutte le sedi associate a un utente.
Per elencare tutte le sedi di proprietà diretta 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 per includere le
schede di proprietà indiretta (di proprietà o gestite tramite un gruppo):
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}
Filtrare i risultati quando elenchi le sedi
Puoi utilizzare i filtri per limitare i risultati 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 di base delle query
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
tabella di seguito).
Le virgolette sono codificate come "%22" e gli spazi come segni più (+).
Salvo diversa indicazione, tutti i confronti sono confronti di token senza distinzione tra maiuscole e minuscole. Ad esempio, "4 drive" corrisponde a "4, Privet Drive".
Combinare 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
Il seguente esempio mostra un'espressione di filtro che restituisce tutte le sedi 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
Cercare per distanza o account
Il seguente esempio mostra come cercare le sedi 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 sedi entro 1600 km 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 di filtro supportati
Di seguito è riportato un elenco esaustivo di tutti i campi che possono essere utilizzati per il filtraggio:
| Campi | Descrizione ed esempio |
|---|---|
| Campi di corrispondenza delle stringhe | |
title |
Il nome reale dell'attività
|
categories |
La combinazione della categoria principale e delle categorie aggiuntive. Tieni presente che "gcid:" deve essere omesso. Se sono presenti più categorie, questo filtro corrisponde 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/dell'area geografica dell'indirizzo
|
storefront_address.administrative_area |
La suddivisione amministrativa di grado più alto usata per l'indirizzo postale di un paese o di un'area geografica
|
storefront_address.locality |
La parte dell'indirizzo relativa alla città/al paese
|
storefront_address.postal_code |
Il codice postale dell'indirizzo
|
metadata.place_id |
Se questa sede è stata verificata ed è collegata a/viene visualizzata su Google Maps, questo campo è uguale all'ID luogo della sede
|
openInfo.status |
Indica se la sede è attualmente aperta per l'attività
(
|
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, inclusa la distinzione tra maiuscole e minuscole, e non solo a un token. Ad esempio, se un'etichetta è "XX YY", non corrisponderà né "XX" né "xx yy".
|
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 sede da un punto geografico.
|
Ordinare per campo 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 nel seguente esempio:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode
Applicare una patch a una sede
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:
Aggiungi i campi e i valori aggiornati con il campo della sede e utilizza un elenco di campi aggiornati separati da virgole come valore per fieldMask.
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}