Ce tutoriel vous explique comment créer et modifier les données sur les établissements. L'API My Business Business Information vous permet d'effectuer les actions suivantes:
- Créez un établissement.
- Supprimer un établissement
- Obtenir un établissement par nom de ressource
- Lister tous les établissements associés à un compte
- Mettre à jour un ou plusieurs champs d'un établissement
Vous pouvez utiliser des établissements dans Ads, mais ils doivent être validés pour apparaître dans la recherche Google et sur Maps. Les données sur les établissements sont représentées par la collection accounts.locations.
Avant de commencer
Avant d'utiliser l'API My Business Business Information, vous devez enregistrer votre application et obtenir des identifiants OAuth 2.0. Pour savoir comment vous lancer avec l'API My Business Business Information, consultez Configuration de base.
Créer un établissement
Vous pouvez utiliser l'API My Business Business Information afin de créer un établissement pour une entreprise à l'aide de accounts.locations.create.
Pour créer un établissement, utilisez le code suivant:
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" } } }
Supprimer un établissement
Vous pouvez utiliser l'API My Business Business Information pour supprimer un établissement à l'aide de locations.delete.
Pour supprimer un établissement, utilisez le code suivant:
DELETE https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Obtenir un établissement par son nom
Si de nombreux établissements sont associés à votre compte, nous vous conseillons de n'en obtenir qu'un seul. Vous pouvez filtrer par nom d'entreprise pour obtenir un établissement spécifique à l'aide de locations.get.
Pour obtenir un établissement par son nom, utilisez le code suivant. Vous devez spécifier un readMask pour récupérer des champs spécifiques. :
GET https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
Renvoyer la version Google Maps
Pour renvoyer la version Google Maps d'un établissement, ajoutez googleUpdated
à l'URL de la requête, comme dans l'exemple suivant:
GET https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
En l'absence de résultats, un code d'état HTTP 404 NOT FOUND
est renvoyé. Pour en savoir plus sur la gestion des mises à jour Google, cliquez ici.
Répertorier les emplacements
Si vous gérez un ou plusieurs établissements, vous pouvez lister tous ceux associés à votre compte. Utilisez l'API accounts.locations.list pour répertorier tous les établissements associés à un utilisateur.
Pour répertorier tous les établissements directement détenus ou gérés par un utilisateur authentifié, utilisez le code suivant:
GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}
Utilisez le caractère générique '-'
pour le compte dans l'URL de la requête afin d'inclure les fiches détenues indirectement (détenues ou gérées par un groupe):
GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}
Filtrer les résultats lorsque vous répertoriez des lieux
Vous pouvez utiliser des filtres pour limiter les résultats renvoyés lorsque vous appelez accounts.locations.list. Pour filtrer une requête, ajoutez une expression de filtre à l'URL de base, comme indiqué dans l'exemple suivant:
GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22
Syntaxe des requêtes de base
Une restriction utilise la syntaxe suivante : <field><operator><value>
, où l'opérateur est EQUALS (=) ou HAS (:). Les opérateurs EQUALS (=) et HAS (:) sont équivalents pour tous les champs, à l'exception de locationName
(voir le tableau ci-dessous).
Les guillemets sont encodés avec "%22", et les espaces avec le signe plus (+).
Sauf indication contraire, toutes les comparaisons sont des comparaisons de jetons non sensibles à la casse. Par exemple, "4 république" peut être mis en correspondance avec "4, Place de la République".
Combiner plusieurs champs dans une requête de filtre
L'API permet à l'opérateur AND d'associer toutes les restrictions applicables aux champs. Toutefois, lorsqu'il s'agit du mot clé OR, toutes les restrictions doivent s'appliquer au même champ. Par exemple, locationName=A
OR labels=B
n'est pas autorisé.
Exemple
L'exemple suivant illustre une expression de filtre qui renvoie tous les établissements portant le nom "Pepé Le Pew". Elle indique les catégories correspondant à "french_restaurant" ou "european_restaurant", ainsi que le libellé "newly open".
locationName=%22Pepé+Le+Pew%22+AND+ (categories=%22french_restaurant%22+OR+ categories=%22european_restaurant%22)+AND+ labels=%22newly+open%22
Rechercher par distance ou par compte
L'exemple suivant montre comment rechercher des établissements situés dans un certain périmètre à partir d'un point géographique:
GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}
Pour filtrer les établissements situés dans un rayon de 1 000 miles autour de Boulder, Colorado, aux États-Unis:
GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(40.01, -105.27))<1000.0
Liste de tous les champs de filtre acceptés
Voici une liste exhaustive de tous les champs pouvant être utilisés pour le filtrage:
Fields | Description et exemple |
---|---|
Champs de mise en correspondance de chaînes | |
title |
Nom réel de l'entreprise
|
categories |
Combinaison de la catégorie principale et des catégories supplémentaires. Notez que "gcid:" doit être omis. S'il existe plusieurs catégories, ce filtre correspond si au moins une catégorie correspond au modèle.
|
phone_numbers.primary_phone |
Numéro de téléphone principal au format E.164 (par exemple, "+441234567890").
|
storefront_address.region_code |
Code CLDR du pays ou de la région associés à l'adresse
|
storefront_address.administrative_area |
Subdivision administrative la plus élevée utilisée pour les adresses postales d'un pays ou d'une région
|
storefront_address.locality |
La partie ville de l'adresse
|
storefront_address.postal_code |
Le code postal de l'adresse
|
metadata.place_id |
Si cet établissement a été validé et s'il est associé à/apparaît sur Google Maps, ce champ correspond à l'identifiant du lieu.
|
openInfo.status |
Indique si l'établissement est actuellement ouvert (
|
labels |
Ensemble de chaînes au format libre pour vous permettre d'ajouter des tags à votre établissement. Contrairement à tous les autres champs, cette valeur doit correspondre exactement à un libellé complet (en respectant la casse) et pas seulement à un jeton. Par exemple, si un libellé est "XX YY", ni "XX", ni "xx yy" ne correspondront.
|
storeCode |
Identifiant externe associé à cet établissement, qui doit être unique au sein d'un compte donné
|
Fonctions | |
distance |
Permet de filtrer les données en fonction de la distance entre l'établissement et un point géographique
|
Trier par champ de requête
Vous pouvez trier les résultats par nom d'entreprise ou code de magasin, par ordre croissant ou décroissant. Plusieurs critères de tri sont séparés par une virgule dans la chaîne orderBy
, comme dans l'exemple suivant:
GET https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode
Appliquer un correctif à un établissement
Utilisez l'API My Business Business Information pour mettre à jour un ou plusieurs champs d'un établissement à l'aide de locations.patch.
Pour modifier un ou plusieurs champs d'un établissement, utilisez le code suivant:
Ajoutez les champs et les valeurs mises à jour avec le champ "location", puis utilisez une liste de champs mis à jour séparés par une virgule comme valeur pour fieldMask
.
PATCH https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title { "title": "Google Shoes" }