Konum arama | Listings API

Parametreler

Sorgu

Ad	Tür	Zorunlu	Açıklama	Varsayılan
query	string	isteğe bağlı	Search keyword matched against location name, street address, city, and store ID. Omit to page through every location.	—
filter	string	isteğe bağlı	JSON-encoded filter object to narrow results (for example by approval status).	—
first	integer	isteğe bağlı	Number of records to fetch, starting from the most recent.	50
after	string	isteğe bağlı	Cursor to fetch records after (forward pagination). Pass the previous page's `pageInfo.endCursor`.	—

Yanıtlar

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.

Konumları serbest metin biçiminde bir anahtar kelimeyle bulmak için bu endpoint'i kullanın. Anahtar kelime konum adı, açık adres, şehir ve mağaza kimliğiyle eşleştirilir; böylece kullanıcı markayı, bir cadde adını veya dahili bir mağaza kodunu yazmış olsa da ?query=Jenny gibi tek bir sorgu "Jenny Home" konumunu bulur.

Kullanım örneği: yazarken arama yapan konum seçici. Bir kontrol panelindeki "konumlarınızı arayın" kutusunu desteklemek için her tuş vuruşunda (debounce uygulayarak) GET /locations/search?query=<term>&first=10 çağrısı yapın ve edges[].node.name öğesini databaseId ile görüntüleyin. Düğüm tam adresi, kategoriyi ve approved durumunu içerdiğinden, ikinci bir sorguya gerek kalmadan ayrıntılı bir sonuç satırı gösterebilirsiniz.

Kullanım örneği: kendi sisteminizle karşılaştırarak doğrulama. Bir güncelleme göndermeden önce mağazanın Listings API içinde mevcut olduğunu doğrulamak için kendi storeId değerinizle arama yapın; boş bir edges dizisi, konumun henüz oluşturulmadığı anlamına gelir.

Sayfalama ve dikkat edilmesi gerekenler.

Sonuçlar imleç tabanlı olarak sayfalanır. Sonraki sayfayı almak için önceki yanıtın pageInfo.endCursor değerini after olarak iletin ve hasNextPage değeri false olduğunda durun. Sayfa düzeyindeki sayının totalCount değil, pageInfo.total olduğunu unutmayın.
query parametresini belirtmezseniz konumlarınız filtrelenmeden (first sınırına tabi olarak) döndürülür; bu, hesabın tamamını sayfa sayfa almak için kullanışlı bir yöntemdir.
Arama, hesabın istek hızı sınırını paylaşır. 429 aldığınızda, yeniden denemeden önce Retry-After başlığını kullanarak bekleyin.

Eşleşen her konum için placeActionLinks (Listings API tarafından yönetilen Google işlem bağlantıları) ve discoveredPlaceActionLinks (doğrudan işletmenin Google profilinde bulunan ve henüz yönetilmeyen bağlantılar) döndürülür. Yer işlem bağlantıları kılavuzuna bakın.