이 가이드에서는 위치 데이터를 만들고 수정하는 방법을 보여줍니다. My Business Business Information API를 사용하면 다음 작업을 처리할 수 있습니다.
Google Ads에서 위치를 사용할 수 있지만 위치가 Google 검색 및 지도에 표시되려면 인증을 받아야 합니다. 위치 데이터는 accounts.locations 컬렉션으로 표시됩니다.
시작하기 전에
My Business Business Information API를 사용하기 전에 애플리케이션을 등록하고 OAuth 2.0 사용자 인증 정보를 획득해야 합니다. My Business Business Information API를 시작하는 방법에 관한 자세한 내용은 기본 설정을 참고하세요.
위치 만들기
My Business Business Information API를 사용하여 accounts.locations.create로 비즈니스의 새 위치를 만들 수 있습니다.
위치를 만들려면 다음 코드를 사용하세요.
POST
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?requestId=requestId&validateOnly=True|False
{
"storeCode": "GOOG-SYD",
"languageCode": "en-AU",
"title": "Google Sydney",
"phoneNumbers": {
"primaryPhone": "02 9374 4000"
}
"storefrontAddress": {
"addressLines": [
"Level 5",
"48 Pirrama Road"
],
"locality": "Pyrmont",
"postalCode": "2009",
"administrativeArea": "NSW",
"regionCode": "AU"
},
"websiteUri": "https://www.google.com.au/",
"regularHours": {
"periods": [
{
"openDay": "MONDAY",
"closeDay": "MONDAY",
"openTime": "09:00",
"closeTime": "17:00"
},
{
"openDay": "TUESDAY",
"closeDay": "TUESDAY",
"openTime": "09:00",
"closeTime": "17:00"
},
{
"openDay": "WEDNESDAY",
"closeDay": "WEDNESDAY",
"openTime": "09:00",
"closeTime": "17:00"
},
{
"openDay": "THURSDAY",
"closeDay": "THURSDAY",
"openTime": "09:00",
"closeTime": "17:00"
},
{
"openDay": "FRIDAY",
"closeDay": "FRIDAY",
"openTime": "09:00",
"closeTime": "17:00"
}
]
},
"categories": {
"primaryCategory": {
"name": "gcid:software_company"
}
}
}
위치 삭제하기
My Business Business Information API를 사용하여 locations.delete로 위치를 삭제할 수 있습니다.
위치를 삭제하려면 다음 코드를 사용하세요.
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
이름별로 위치 가져오기
계정과 연결된 비즈니스가 많은 경우 하나의 위치를 가져오는 것이 좋습니다. 비즈니스 이름으로 필터링하면 locations.get으로 특정 위치를 가져올 수 있습니다.
이름으로 위치를 가져오려면 다음 코드를 사용하세요. 특정 필드를 가져오려면 readMask를 지정해야 합니다. :
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
Google 지도 버전 반환
위치의 Google 지도 버전을 반환하려면 다음 예와 같이
요청 URL에 googleUpdated를 추가합니다.
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
결과가 없으면 404 NOT FOUND HTTP 상태 코드가 반환됩니다. Google 업데이트 관리에 관한 자세한 내용은 여기를 참고하세요.
위치 나열
하나 이상의 위치를 관리하는 경우 계정과 연결된 모든 위치를 나열할 수 있습니다. accounts.locations.list API를 사용하여 사용자와 연결된 모든 위치의 목록을 생성합니다.
인증된 사용자가 직접 소유하거나 관리하는 모든 위치의 목록을 생성하려면 다음을 사용합니다.
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}
요청 URL에서 계정에 대한 '-' 와일드 카드를 사용하여 간접적으로 소유한
목록(그룹을 통해 소유 또는 관리)을 포함합니다.
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}
위치 목록 생성 시 결과 필터링
필터를 사용하여 accounts.locations.list를 호출할 때 반환되는 결과를 제한할 수 있습니다. 요청을 필터링하려면 다음 예와 같이 기준 URL에 필터 표현식을 추가합니다.
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22
기본 쿼리 구문
제한 사항에는 <field><operator><value> 구문이 있으며,
여기에서
연산자는 EQUALS (=) 또는 HAS (:)입니다. EQUALS (=) 및
HAS (:) 연산자는 locationName을 제외한 모든 필드에서 동일합니다(아래
표 참고).
따옴표는 '%22'로, 공백은 더하기 기호(+)로 인코딩됩니다.
달리 명시되지 않는 한 모든 비교는 대소문자를 구분하지 않는 토큰 비교입니다. 예를 들어 '4 drive'는 '4, Privet Drive'와 일치합니다.
필터 쿼리에 여러 필드 결합하기
API를 사용하면 AND로 모든 필드 제한을 연결할 수 있습니다. 그러나
OR 키워드의 경우 모든 제한사항을 동일한 필드에 적용해야
합니다. 예를 들어 locationName=A OR labels=B는
허용되지 않습니다.
예
다음 예시는 이름이 'Pepé Le Pew'인 모든 위치를 반환하는 필터 표현식을 보여줍니다. 'french_restaurant' 또는 european_restaurant' 카테고리와 'newly open' 라벨이 표시됩니다.
locationName=%22Pepé+Le+Pew%22+AND+ (categories=%22french_restaurant%22+OR+ categories=%22european_restaurant%22)+AND+ labels=%22newly+open%22
거리 또는 계정으로 검색
다음 예시에서는 하나의 지리적 지점에서 특정 거리 이내에 있는 위치의 검색 방법을 보여줍니다.
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}
미국 콜로라도주 볼더에서 1,000마일 이내의 위치를 필터링하는 방법:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(40.01, -105.27))<1000.0
지원되는 모든 필터 필드의 목록
다음은 필터링에 사용할 수 있는 모든 필드의 전체 목록입니다.
| 필드 | 설명 및 예 |
|---|---|
| 문자열 일치 필드 | |
title |
비즈니스의 실제 이름입니다.
|
categories |
기본 카테고리와 추가 카테고리의 조합입니다. 'gcid:'는 생략해야 합니다. 카테고리가 여러 개인 경우 하나 이상의 카테고리가 이 패턴과 일치하면 이 필터는 일치합니다.
|
phone_numbers.primary_phone |
E.164 형식의 기본 전화번호(예: '+441234567890')입니다.
|
storefront_address.region_code |
주소의 국가/지역에 해당하는 CLDR 지역 코드입니다.
|
storefront_address.administrative_area |
국가 또는 지역의 주소에 사용되는 가장 높은 행정 구역 단위입니다.
|
storefront_address.locality |
주소의 시/군/구입니다.
|
storefront_address.postal_code |
주소의 우편번호입니다.
|
metadata.place_id |
이 위치가 인증되어 Google 지도에 연결/표시될 경우 필드는 위치의 장소 ID와 동일합니다.
|
openInfo.status |
위치가 현재 영업 중인지 여부를 나타냅니다(
|
labels |
비즈니스를 태그할 수 있는 자유 형식의 문자열 컬렉션입니다. 다른 모든 필드와 달리 이 값은 토큰뿐 아니라 대소문자를 포함한 전체 라벨과 정확히 일치해야 합니다. 예를 들어 라벨이 'XX YY'인 경우 'XX' 또는 'xx yy'는 일치하지 않습니다.
|
storeCode |
이 위치의 외부 식별자이며 주어진 계정 내에서 고유해야 합니다.
|
| 함수 | |
distance |
지리적 지점으로부터 위치의 거리를 기준으로 필터링할 수 있습니다.
|
쿼리 필드별 정렬
비즈니스 이름별 또는 상점 코드별 결과를 오름차순 또는 내림차순으로
정렬할 수 있습니다. 다음 예와 같이 여러 정렬 기준은 orderBy 문자열에서
쉼표로 구분됩니다.
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode
위치에 패치 적용
My Business Business Information API를 사용하여 locations.patch로 위치의 필드를 하나 이상 업데이트할 수 있습니다.
위치의 필드를 하나 이상 변경하려면 다음 코드를 사용하세요.
위치 필드로 필드와 업데이트된 값을 추가하고, 업데이트 및
쉼표로 구분된 필드 목록을 fieldMask 값으로 사용합니다.
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}