Questo tutorial mostra come creare e modificare i dati sulla posizione. L'API Informazioni sull'attività di My Business ti consente di eseguire le seguenti operazioni:
- Crea una nuova stazione di ricarica.
- Eliminare una stazione di ricarica.
- Ottieni una posizione in base al nome della risorsa.
- Elenca tutte le sedi di un account.
- Aggiornare uno o più campi per una stazione di ricarica.
Le sedi possono essere utilizzate in Google Ads, ma devono essere verificate per poter essere visualizzate su Ricerca e Maps. I dati sulla posizione sono rappresentati dalla raccolta accounts.locations.
Prima di iniziare
Prima di utilizzare l'API Informazioni sull'attività di My Business, devi registrare la tua applicazione e ottenere le credenziali OAuth 2.0. Per informazioni dettagliate su come iniziare a utilizzare l'API Informazioni sull'attività di My Business, consulta la sezione Configurazione di base.
Creare una stazione di ricarica
Puoi utilizzare l'API Informazioni sull'attività di My Business per creare una nuova sede per un'attività con accounts.locations.create.
Per creare una stazione di ricarica:
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 stazione di ricarica
Puoi utilizzare l'API Informazioni sull'attività di My Business per eliminare una sede con locations.delete.
Per eliminare una stazione di ricarica:
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Recuperare una località in base al nome
Se hai molte attività associate al tuo account, ti consigliamo di scegliere una sola sede. Puoi filtrare in base al nome dell'attività per ottenere una località specifica con locations.get.
Per ottenere una località per nome, utilizza quanto segue. Devi specificare una maschera di lettura 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 località, aggiungi
googleUpdated all'URL della richiesta, come nell'esempio seguente:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
Se non vengono visualizzati risultati, viene restituito un codice di stato HTTP 404 NOT FOUND. Puoi trovare ulteriori dettagli sulla gestione degli aggiornamenti Google qui.
Elenco località
Se 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à 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 query di base
Una limitazione ha la seguente sintassi:
<field><operator><value>,
dove l'operatore è È UGUALE A (=) o HA (:). Gli operatori È UGUALE A (=) e HA (:)
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 di token senza sensibilità alle maiuscole. Ad esempio, "4 via" corrisponde a "4, via Privet".
Combinare più campi in una query di filtro
L'API consente di collegare tutte le limitazioni dei campi con AND. Tuttavia,
quando si tratta della parola chiave OR, tutte le limitazioni devono essere applicate allo stesso
campo. Ad esempio, locationName=A OPPURE labels=B non è consentito.
Esempio
L'esempio seguente 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 un'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}
Per filtrare le località entro 1600 km da Boulder, Colorado, Stati Uniti:
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 i filtri:
| 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 nel formato E.164 (ad es. "+441234567890").
|
storefront_address.region_code |
Il codice regione CLDR del paese/della regione 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 di città dell'indirizzo
|
storefront_address.postal_code |
Il codice postale dell'indirizzo
|
metadata.place_id |
Se questa località è stata verificata ed è collegata a/visualizzata su Google Maps, questo campo è uguale all'ID luogo della località
|
openInfo.status |
Indica se la sede è attualmente aperta o meno
(
|
labels |
Una raccolta di stringhe di tipo libero che ti consente di taggare la tua attività. diversamente da tutti gli altri campi, questo valore deve corrispondere esattamente a un'etichetta completa, incluse le maiuscole, e non solo a un token. Ad esempio, se un'etichetta è "XX YY", né "XX" né "xx yy" corrisponderanno.
|
storeCode |
Identificatore esterno per questa località, che deve essere univoco all'interno di un determinato account
|
| Funzioni | |
distance |
Consente di filtrare in base alla distanza della località da un punto geografico.
|
Ordina per campo della query
Puoi ordinare i risultati in base al nome dell'attività o al codice negozio, in ordine crescente o discendente. Più criteri di ordinamento sono separati da virgole nella stringaorderBy, come nell'esempio seguente:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode
Eseguire il patching di una stazione di ricarica
Utilizza l'API Informazioni sull'attività di My Business per aggiornare uno o più campi per una sede con locations.patch.
Per modificare uno o più campi per una stazione di ricarica, utilizza quanto segue:
Aggiungi i campi e i valori aggiornati con il campo posizione 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"
}