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éer 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 utiliser 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, vous avez la possibilité de n'en obtenir qu'un seul. Vous pouvez filtrer les résultats par nom 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 s'affiche. Pour savoir comment gérer les mises à jour Google, cliquez ici.

Lister les établissements

Si vous gérez un ou plusieurs établissements, vous pouvez lister tous ceux associés à votre compte. Utilisez l'API accounts.locations.list pour lister tous les établissements associés à un utilisateur.

Pour lister tous ceux 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 listez des établissements

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22

Syntaxe des requêtes de base

Utilisez la syntaxe suivante pour définir une restriction : <field><operator><value>, où l'opérateur est soit EQUALS (=), soit HAS (:). Les opérateurs EQUALS (=) et HAS (:) sont les mêmes pour tous les champs, sauf le champ 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 vous permet d'utiliser AND pour associer toutes les restrictions applicables aux champs. Toutefois, si vous utilisez le 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

Dans l'exemple suivant, une expression de filtre 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 vous 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

La liste exhaustive suivante présente 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"
}