Pesquisar locais | Listings API

Parâmetros

Query

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

Respostas

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.

Use este endpoint para encontrar locais por uma palavra-chave em texto livre. A palavra-chave é comparada com o nome do local, o endereço, a cidade e o ID da loja, de modo que uma única consulta como ?query=Jenny encontra "Jenny Home", independentemente de o usuário ter digitado a marca, uma rua ou um código interno da loja.

Caso de uso: seletor de locais com sugestões durante a digitação. Para implementar uma caixa de "pesquise seus locais" em um painel, chame GET /locations/search?query=<term>&first=10 a cada tecla pressionada (com debounce) e renderize edges[].node.name com databaseId. Como o nó contém o endereço completo, a categoria e o status de approved, você pode exibir uma linha de resultado com informações detalhadas sem uma segunda consulta.

Caso de uso: conciliar com seu próprio sistema. Para confirmar que uma loja existe na Listings API antes de enviar uma atualização, pesquise pelo seu valor de storeId; um array edges vazio significa que o local ainda não foi criado.

Paginação e pontos de atenção.

Os resultados usam paginação por cursor. Passe o pageInfo.endCursor da resposta anterior como after para buscar a próxima página e pare quando hasNextPage for false. Observe que a contagem por página é pageInfo.total, não totalCount.
Omitir query retorna seus locais sem filtragem (sujeitos a first), o que é uma maneira conveniente de percorrer toda a conta por páginas.
A pesquisa compartilha o limite de requisições da conta. Ao receber 429, aguarde conforme indicado pelo cabeçalho Retry-After antes de tentar novamente.

Cada local correspondente retorna placeActionLinks (os links de ação do Google gerenciados pela Listings API) e discoveredPlaceActionLinks (links encontrados diretamente no perfil da empresa no Google que ainda não são gerenciados). Consulte o guia de links de ação de locais.