Listings APIListings API
Se connecter
GET/api/v4/locations/search

Rechercher des établissements

Renvoie une liste d'établissements paginée par curseur correspondant à un mot-clé, avec une recherche possible par nom, adresse ou identifiant de magasin.

Nécessite une clé API. Consultez Authentification pour le format de l’en-tête et la rotation des clés.

Paramètres

Chaîne de requête

NomTypeObligatoireDescriptionPar défaut
querystringfacultatifSearch keyword matched against location name, street address, city, and store ID. Omit to page through every location.—
filterstringfacultatifJSON-encoded filter object to narrow results (for example by approval status).—
firstintegerfacultatifNumber of records to fetch, starting from the most recent.50
afterstringfacultatifCursor to fetch records after (forward pagination). Pass the previous page's `pageInfo.endCursor`.—

Réponses

200Cursor-paginated list of matching locations.
Response
{  "data": {    "searchLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "accountId": 12345,            "accountName": "owner@brightsmile-dental.com",            "addOns": [],            "additionalCategoryIds": [],            "additionalCategoryNames": [],            "additionalGbpSiteCategoryIds": [],            "additionalGbpSiteCategoryNames": [],            "additionalInfo": null,            "additionalPhones": [],            "aiAnalyticsEnabled": false,            "approved": "APPROVED",            "archivalScheduledAt": null,            "archived": false,            "archivedAt": null,            "bizUrl": null,            "bizUrlUtm": false,            "bookingUrl": null,            "businessHours": [],            "cancellationScheduledAt": null,            "categoryId": 15,            "city": "Austin",            "clientName": "owner@brightsmile-dental.com",            "contentPreferredLanguage": "ENGLISH",            "countryCode": "1",            "countryIso": "US",            "createErrors": [],            "createdDate": "July 06, 2026",            "customAttributes": [],            "databaseId": 1800289,            "defaultAgencyTag": "ownerbrightsmiledentalcom",            "description": "This is a standalone duplex house. A comfortable, private residence located in the Bouldin Creek neighborhood of Austin.",            "discoveredPlaceActionLinks": [],            "enabledSiteIds": [],            "facebookUrl": null,            "franchise": false,            "googleAdsPhone": null,            "googleVerificationStatus": { "message": null, "status": "NOT_CONNECTED" },            "googleplusUrl": null,            "hideAddress": false,            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "instagramUrl": null,            "isRestaurant": true,            "lastUpdatedDate": "July 06, 2026",            "latitude": "30.2711286",            "linkedinUrl": null,            "locationPhotos": [],            "longitude": "-97.7436995",            "managedServiceSiteBuckets": [],            "managedServiceSites": [],            "moreHours": [],            "name": "Jenny Home",            "offeringsUrl": null,            "ownerEmail": null,            "ownerName": null,            "package": "PREMIUM",            "paymentMethods": [],            "phone": "5125550142",            "pinterestUrl": null,            "placeActionLinks": [],            "planId": 3797,            "planName": "Launch",            "postalCode": "78701",            "primaryGbpSiteCategoryId": null,            "primaryGbpSiteCategoryName": null,            "publisherAttributes": [],            "reservationUrl": null,            "serviceArea": null,            "serviceItems": [],            "stateIso": "TX",            "stateName": "Texas",            "storeId": null,            "street": "600 Congress Ave, Suite 200",            "street1": null,            "subCategoryId": 1432,            "subCategoryName": "Restaurants",            "tagline": null,            "temporarilyClosed": false,            "tiktokUrl": null,            "toplineMessage": null,            "twitterUrl": null,            "uid": "3c92283c-6145-4a43-8a62-0c15fd712021",            "updatedAt": "2026-07-06T18:33:29.664Z",            "videos": [],            "voiceStatus": 3,            "yearOfIncorporation": null,            "youtubeUrl": null          }        }      ],      "pageInfo": {        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "hasNextPage": false,        "hasPreviousPage": false,        "total": 1      }    }  }}
401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.

Utilisez cet endpoint pour trouver des établissements à l'aide d'un mot-clé en texte libre. Le mot-clé est recherché dans le nom de l'établissement, l'adresse postale, la ville et l'identifiant de magasin, de sorte qu'une seule requête comme ?query=Jenny permet de trouver "Jenny Home", que l'utilisateur ait saisi la marque, une rue ou un code de magasin interne.

Cas d'utilisation : sélecteur d'établissement avec recherche à la saisie. Pour alimenter un champ "Rechercher vos établissements" dans un tableau de bord, appelez GET /locations/search?query=<term>&first=10 à chaque frappe (avec temporisation) et affichez edges[].node.name avec databaseId. Comme le nœud contient l'adresse complète, la catégorie et le statut approved, vous pouvez afficher une ligne de résultat détaillée sans effectuer une seconde recherche.

Cas d'utilisation : rapprochement avec votre propre système. Pour vérifier qu'un magasin existe dans Listings API avant d'envoyer une mise à jour, effectuez une recherche à partir de votre valeur storeId ; un tableau edges vide signifie que l'établissement n'a pas encore été créé.

Pagination et points d'attention.

  • Les résultats sont paginés par curseur. Transmettez la valeur pageInfo.endCursor de la réponse précédente comme after pour récupérer la page suivante, et arrêtez-vous lorsque hasNextPage vaut false. Notez que le nombre de résultats de la page est indiqué par pageInfo.total, et non par totalCount.
  • Si vous omettez query, vos établissements sont renvoyés sans filtrage (sous réserve de first), ce qui constitue un moyen pratique de parcourir l'ensemble du compte page par page.
  • La recherche partage la limite de requêtes du compte. En cas de 429, attendez en vous basant sur l'en-tête Retry-After avant de réessayer.

Pour chaque établissement correspondant, la réponse contient placeActionLinks (les liens d'action Google gérés par Listings API) et discoveredPlaceActionLinks (les liens trouvés directement sur la fiche Google de l'entreprise qui ne sont pas encore gérés). Consultez le guide des liens d'action pour les établissements.

Request
curl -X GET 'https://listingsapi.com/api/v4/locations/search' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground