사업장 검색 | Listings API

매개변수

쿼리

이름	유형	필수	설명	기본값
query	string	선택	Search keyword matched against location name, street address, city, and store ID. Omit to page through every location.	—
filter	string	선택	JSON-encoded filter object to narrow results (for example by approval status).	—
first	integer	선택	Number of records to fetch, starting from the most recent.	50
after	string	선택	Cursor to fetch records after (forward pagination). Pass the previous page's `pageInfo.endCursor`.	—

응답

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.

이 엔드포인트를 사용하여 자유 텍스트 키워드로 사업장을 찾습니다. 키워드는 사업장 이름, 도로명 주소, 도시 및 매장 ID와 대조되므로, 사용자가 브랜드, 도로명 또는 내부 매장 코드를 입력하더라도 ?query=Jenny와 같은 단일 쿼리로 "Jenny Home"을 찾을 수 있습니다.

사용 사례: 입력 시 검색 결과를 표시하는 사업장 선택기. 대시보드의 "사업장 검색" 입력란을 구현하려면 키를 입력할 때마다 디바운스를 적용하여 GET /locations/search?query=<term>&first=10을 호출하고 edges[].node.name을 databaseId와 함께 표시합니다. 노드에는 전체 주소, 카테고리 및 approved 상태가 포함되므로 추가 조회 없이 상세한 검색 결과 행을 표시할 수 있습니다.

사용 사례: 자체 시스템과 대조. 업데이트를 전송하기 전에 Listings API에 매장이 존재하는지 확인하려면 자체 시스템의 storeId 값으로 검색합니다. edges 배열이 비어 있으면 해당 사업장이 아직 생성되지 않았음을 의미합니다.

페이지네이션 및 주의 사항.

결과에는 커서 기반 페이지네이션이 적용됩니다. 다음 페이지를 가져오려면 이전 응답의 pageInfo.endCursor를 after로 전달하고, hasNextPage가 false이면 중단합니다. 페이지 단위 개수는 totalCount가 아니라 pageInfo.total입니다.
query를 생략하면 first의 제한 내에서 사업장이 필터링 없이 반환되므로, 계정 전체의 사업장을 페이지 단위로 조회할 때 편리합니다.
검색에도 다른 호출과 같은 계정 요청 빈도 제한이 적용됩니다. 429가 발생하면 Retry-After 헤더를 사용하여 대기한 후 재시도합니다.

일치하는 각 사업장에 대해 placeActionLinks(Listings API가 관리하는 Google 작업 링크)와 discoveredPlaceActionLinks(업체의 Google 프로필에서 직접 발견되었으며 아직 관리되지 않는 링크)가 반환됩니다. 장소 작업 링크 가이드를 참조합니다.