Buscar ubicaciones | Listings API

Parámetros

Consulta

Nombre	Tipo	Obligatorio	Descripción	Predeterminado
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`.	—

Respuestas

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 este endpoint para buscar ubicaciones mediante una palabra clave de texto libre. La palabra clave se compara con el nombre de la ubicación, la dirección postal, la ciudad y el ID de tienda, de modo que una sola consulta como ?query=Jenny encuentra "Jenny Home" tanto si el usuario ha escrito la marca como una calle o un código interno de tienda.

Caso de uso: selector de ubicaciones con búsqueda mientras escribes. Para implementar un cuadro de "busca tus ubicaciones" en un panel, llama a GET /locations/search?query=<term>&first=10 con cada pulsación de tecla (con un retardo para agrupar las pulsaciones) y muestra edges[].node.name con databaseId. Como el nodo incluye la dirección completa, la categoría y el estado de approved, puedes mostrar una fila de resultados detallada sin una segunda consulta.

Caso de uso: cotejar con tu propio sistema. Para confirmar que una tienda existe en Listings API antes de enviar una actualización, busca por tu valor de storeId; un array edges vacío significa que la ubicación aún no se ha creado.

Paginación y aspectos que debes tener en cuenta.

Los resultados se paginan mediante cursores. Pasa el valor de pageInfo.endCursor de la respuesta anterior como after para obtener la página siguiente y detente cuando hasNextPage sea false. Ten en cuenta que el recuento por página es pageInfo.total, no totalCount.
Si omites query, se devuelven tus ubicaciones sin filtrar (sujetas a first), lo que resulta práctico para recorrer toda la cuenta por páginas.
La búsqueda comparte el límite de solicitudes de la cuenta. Si recibes un 429, espera el tiempo indicado en la cabecera Retry-After antes de volver a intentarlo.

Para cada ubicación coincidente, se devuelven placeActionLinks (los enlaces de acción de Google que gestiona Listings API) y discoveredPlaceActionLinks (los enlaces que se encuentran directamente en el perfil de Google del negocio y que aún no se gestionan). Consulta la guía de enlaces de acción de lugares.