Cerca sedi | Listings API

Parametri

Query

Nome	Tipo	Obbligatorio	Descrizione	Predefinito
query	string	facoltativo	Search keyword matched against location name, street address, city, and store ID. Omit to page through every location.	—
filter	string	facoltativo	JSON-encoded filter object to narrow results (for example by approval status).	—
first	integer	facoltativo	Number of records to fetch, starting from the most recent.	50
after	string	facoltativo	Cursor to fetch records after (forward pagination). Pass the previous page's `pageInfo.endCursor`.	—

Risposte

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.

Usa questo endpoint per trovare sedi tramite una parola chiave in testo libero. La parola chiave viene confrontata con il nome della sede, l'indirizzo, la città e l'ID del negozio, quindi una singola query come ?query=Jenny trova "Jenny Home" sia che l'utente abbia digitato il marchio, una via o un codice interno del negozio.

Caso d'uso: selettore di sedi con ricerca durante la digitazione. Per alimentare una casella "cerca le tue sedi" in una dashboard, chiama GET /locations/search?query=<term>&first=10 a ogni pressione di un tasto (applicando il debounce) e visualizza edges[].node.name con databaseId. Poiché il nodo contiene l'indirizzo completo, la categoria e lo stato approved, puoi mostrare una riga di risultato dettagliata senza una seconda ricerca.

Caso d'uso: riconciliazione con il tuo sistema. Per verificare che un negozio esista in Listings API prima di inviare un aggiornamento, cerca usando il tuo valore storeId; un array edges vuoto indica che la sede non è ancora stata creata.

Paginazione e aspetti a cui prestare attenzione.

I risultati sono paginati tramite cursore. Passa pageInfo.endCursor della risposta precedente come after per recuperare la pagina successiva e fermati quando hasNextPage è false. Nota che il conteggio a livello di pagina è pageInfo.total, non totalCount.
Se ometti query, vengono restituite le tue sedi senza filtri (nel rispetto di first), un modo pratico per scorrere tutte le sedi dell'account pagina per pagina.
La ricerca condivide il limite di frequenza dell'account. In caso di 429, attendi prima di riprovare, usando l'header Retry-After per determinare il tempo di attesa.

Per ogni sede corrispondente vengono restituiti placeActionLinks (i link alle azioni di Google gestiti da Listings API) e discoveredPlaceActionLinks (i link trovati direttamente sul profilo Google dell'attività che non sono ancora gestiti). Consulta la guida ai link alle azioni dei luoghi.