Utiliser les données sur les établissements

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

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

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}

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:

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:

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