Cari lokasi | Listings API

Parameter

Query

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

Respons

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.

Gunakan endpoint ini untuk menemukan lokasi berdasarkan kata kunci teks bebas. Kata kunci dicocokkan dengan nama lokasi, alamat jalan, kota, dan ID toko, sehingga satu kueri seperti ?query=Jenny menemukan "Jenny Home" baik pengguna mengetik merek, nama jalan, maupun kode toko internal.

Kasus penggunaan: pemilih lokasi dengan pencarian saat mengetik. Untuk mendukung kotak "cari lokasi Anda" di dasbor, panggil GET /locations/search?query=<term>&first=10 setiap kali tombol ditekan (dengan debounce) dan tampilkan edges[].node.name dengan databaseId. Karena node memuat alamat lengkap, kategori, dan status approved, Anda dapat menampilkan baris hasil yang kaya informasi tanpa pencarian kedua.

Kasus penggunaan: rekonsiliasi dengan sistem Anda sendiri. Untuk memastikan toko ada di Listings API sebelum mengirim pembaruan, cari berdasarkan nilai storeId Anda; array edges yang kosong berarti lokasi tersebut belum dibuat.

Paginasi dan hal-hal yang perlu diperhatikan.

Hasil menggunakan paginasi berbasis kursor. Kirim pageInfo.endCursor dari respons sebelumnya sebagai after untuk mengambil halaman berikutnya, dan berhenti saat hasNextPage bernilai false. Perhatikan bahwa jumlah pada tingkat halaman adalah pageInfo.total, bukan totalCount.
Jika query tidak disertakan, lokasi Anda dikembalikan tanpa filter (dengan tetap mengikuti first), sehingga Anda dapat menelusuri seluruh akun halaman demi halaman dengan mudah.
Pencarian menggunakan batas laju yang berlaku bersama untuk seluruh akun. Saat menerima 429, tunda percobaan ulang sesuai header Retry-After.

Setiap lokasi yang cocok mengembalikan placeActionLinks (tautan tindakan Google yang dikelola Listings API) dan discoveredPlaceActionLinks (tautan yang ditemukan langsung di profil Google bisnis tersebut dan belum dikelola). Lihat panduan Tautan Tindakan Tempat.