주변 검색 (신규) 요청은 하나 이상의 장소 유형을 취하고 지정할 수 있습니다. 하나 이상의 데이터 유형을 지정하는 필드 마스크 은(는) 필수입니다. 주변 검색 (신규)은 POST 요청만 지원합니다.
API 탐색기를 사용하면 실시간 요청을 하여 API 및 API 옵션:
실습대화형 서비스 사용해 보기 데모를 사용하여 지도에 표시된 주변 검색 (신규) 결과를 볼 수 있습니다.
주변 검색 (신규) 요청
주변 검색 (신규) 요청은 양식:
https://places.googleapis.com/v1/places:searchNearby
JSON 요청 본문 또는 헤더에 모든 매개변수를 POST 요청을 전송합니다. 예를 들면 다음과 같습니다.
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
주변 지역 검색 (신규) 응답
주변 검색 (신규)은 <ph type="x-smartling-placeholder"></ph> JSON 객체 응답 응답에서 각 항목의 의미는 다음과 같습니다.
places
배열에는 일치하는 모든 장소가 포함됩니다.- 배열의 각 장소는
Place
드림 객체를 지정합니다.Place
객체에는 단일 항목에 관한 자세한 정보가 포함되어 있습니다. 있습니다. - 요청에 전달된 FieldMask는 필드 목록을 지정합니다.
Place
객체에서 반환됩니다.
전체 JSON 객체는 다음과 같은 형식입니다.
{ "places": [ { object (Place) } ] }
필수 매개변수
-
FieldMask
응답 필드 마스크와 같습니다. URL 매개변수를 사용하여 응답 필드 마스크를 메서드에 전달
$fields
또는fields
, 또는 HTTP 헤더 사용X-Goog-FieldMask
입니다. 응답에는 반환된 필드의 기본 목록이 없습니다. 필드 마스크를 생략하면 메서드가 오류를 반환합니다.필드 마스킹은 불필요한 데이터이므로 불필요한 처리 시간과 있습니다.
반환할 장소 데이터 유형의 쉼표로 구분된 목록을 지정합니다. 예를 들어 를 사용하여 장소의 표시 이름과 주소를 가져올 수 있습니다.
X-Goog-FieldMask: places.displayName,places.formattedAddress
*
를 사용하여 모든 필드를 검색합니다.X-Goog-FieldMask: *
다음 필드 중 하나 이상을 지정합니다.
다음 필드는 Nearby Search (Basic) SKU를 트리거합니다.
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.attributions
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.subDestinations
,places.types
,places.utcOffsetMinutes
,places.viewport
*places.name
필드에 리소스 이름 장소가 포함되어 있습니다. 형식은places/PLACE_ID
입니다.places.displayName
을 사용하여 장소의 텍스트 이름에 액세스합니다.다음 필드는 Nearby Search (Advanced) SKU를 트리거합니다.
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
다음 필드는 Nearby Search (Preferred) SKU를 트리거합니다.
places.allowsDogs
,places.curbsidePickup
,places.delivery
,places.dineIn
,places.editorialSummary
,places.evChargeOptions
,places.fuelOptions
,places.goodForChildren
,places.goodForGroups
,places.goodForWatchingSports
,places.liveMusic
,places.menuForChildren
,places.parkingOptions
,places.paymentOptions
,places.outdoorSeating
,places.reservable
,places.restroom
,places.reviews
,places.servesBeer
,places.servesBreakfast
,places.servesBrunch
,places.servesCocktails
,places.servesCoffee
,places.servesDessert
,places.servesDinner
,places.servesLunch
,places.servesVegetarianFood
,places.servesWine
,places.takeout
-
locationRestriction
중심점과 반경(미터)으로 정의되는 원으로 지정되는 검색할 지역입니다. 반경은 0.0 이상, 50000.0 이하여야 합니다. 기본 반경은 0.0입니다. 다음을 수행해야 합니다. 요청에서 0.0보다 큰 값으로 설정하세요.
예:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
선택적 매개변수
-
includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes
유형에서 유형 목록을 지정할 수 있음 필터링에 사용되는 표 A 있습니다. 각 유형 제한 카테고리에 최대 50개의 유형을 지정할 수 있습니다.
한 장소에는 유형에서 단일 기본 유형만 있을 수 있습니다. 다음과 관련된 표 A 있습니다. 예를 들어 기본 유형은
"mexican_restaurant"
또는"steak_house"
사용 결과를 필터링할includedPrimaryTypes
및excludedPrimaryTypes
장소의 기본 유형입니다.또한 장소에는 유형의 여러 유형 값이 있을 수 있습니다. 표 A 관련이 있습니다. 예를 들어 레스토랑의 유형은 다음과 같습니다.
"seafood_restaurant"
,"restaurant"
,"food"
"point_of_interest"
,"establishment"
includedTypes
사용 및excludedTypes
를 사용하여 장소를 가리지 않습니다.일반적인 기본 유형(예:
"restaurant"
또는"hotel"
인 경우 응답에는 지정합니다. 예를 들어"restaurant"
그러면 응답에는"restaurant"
이지만 응답에는 더 구체적인 장소가 포함될 수도 있습니다. 기본 유형(예:"chinese_restaurant"
또는"seafood_restaurant"
)검색이 여러 유형 제한으로 지정된 경우 모든 제한사항을 충족하는 값이 반환됩니다. 예를 들어
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, 반환된 장소는"restaurant"
개의 관련 서비스를 제공하지만 주로 영업하지 않음"steak_house"
로 표현.includedTypes
검색할 테이블 A의 장소 유형을 쉼표로 구분한 목록입니다. 이 매개변수를 생략하면 모든 유형의 장소가 반환됩니다.
excludedTypes
표 A에서 제외할 장소 유형(쉼표로 구분) 목록입니다. 검색
includedTypes
( 예:"school"
) 및excludedTypes
(예:"primary_school"
)를 호출하면"school"
(으)로 분류되었지만 다음 카테고리로 분류되지 않은 장소가 포함된 응답"primary_school"
입니다. 응답에는 다음 중 하나 이상의 장소와 일치하는 장소가 포함됩니다.includedTypes
및excludedTypes
없음.충돌하는 유형이 있는 경우(예: 두
includedTypes
에 모두 나타나는 유형)excludedTypes
이면INVALID_REQUEST
오류가 반환됩니다.includedPrimaryTypes
포함할 테이블 A의 기본 장소 유형의 쉼표로 구분된 목록 찾을 수 있습니다.
excludedPrimaryTypes
제외할 표 A의 기본 장소 유형 목록(쉼표로 구분) 찾을 수 있습니다.
충돌하는 기본 유형이 있는 경우(예:
includedPrimaryTypes
및excludedPrimaryTypes
,INVALID_ARGUMENT
오류가 반환됩니다. -
languageCode
결과를 반환할 때 사용하는 언어입니다.
- 지원되는 언어 목록을 참고하세요. Google은 자주 에서 지원되는 언어를 업데이트하므로 이 목록은 완전하지 않을 수 있습니다.
languageCode
가 제공되지 않으면 API의 기본값은en
입니다. 만약 잘못된 언어 코드를 지정하면 API에서INVALID_ARGUMENT
값을 반환합니다. 오류가 발생했습니다.- API는 사용자와 사용자 모두 읽을 수 있는 상세 주소를 제공하기 위해 최선을 다합니다. 있습니다. 이 목표를 달성하기 위해 상세 주소를 현지 언어로 반환하며 필요한 경우 사용자가 읽을 수 있는 스크립트로 음역하고, 선호하는 있습니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택된 동일한 언어로 반환됩니다.
- 기본 언어로 이름을 사용할 수 없는 경우 API는 가장 유사한 일치 항목을 사용합니다.
- 선호 언어는 API가 선택하는 결과 집합에 약간의 영향을 미칩니다. 반환되는 순서를 선택할 수 있습니다. 지오코더는 약어를 해석하고 도로 유형의 약어, 동의어 등 언어에 따라 다름 한 언어에서는 유효하지만 다른 언어에서는 유효하지 않을 수 있습니다.
-
maxResultCount
반환할 장소 결과의 최대 개수를 지정합니다. 사이여야 합니다. 1부터 20 (기본값)까지 포함됩니다.
-
rankPreference
사용할 순위 유형입니다. 이 매개변수를 생략하면 검색 결과의 순위가 인기도에 따라 결정됩니다. 다음 중 하나일 수 있습니다.
POPULARITY
(기본값): 인기도에 따라 결과를 정렬합니다.DISTANCE
지정할 수 있습니다.
-
regionCode
응답 형식을 지정하는 데 사용되는 지역 코드로, <ph type="x-smartling-placeholder"></ph> 2자리 CLDR 코드 값을 제공합니다. 기본값은 없습니다.
응답의
formattedAddress
필드의 국가 이름이regionCode
인 경우 국가 코드가formattedAddress
에서 생략됩니다. 이 매개변수는 항상 국가를 포함하는adrFormatAddress
에는 영향을 미치지 않습니다. 이름 또는shortFormattedAddress
(포함되지 않음)에 있어야 합니다.대부분의 CLDR 코드는 ISO 3166-1 코드 몇 가지 주목할 만한 예외가 있습니다 예를 들어 영국의 ccTLD는 'uk' (.co.uk), ISO 3166-1 코드는 'gb'입니다. (기술적으로 '영국 및 북아일랜드'의 법인 소유입니다. 매개변수는 관련 법률에 따라 결과에 영향을 미칠 수 있습니다.
주변 검색 (신규) 예
한 가지 유형의 장소 찾기
다음 예는 디스플레이에 대한 Nearby Search (New) 요청을 보여줍니다.
circle
로 정의된 반경 500m 이내의 모든 식당의 이름:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
X-Goog-FieldMask
헤더는 응답이
에는 places.displayName
데이터 필드가 포함됩니다.
응답
형식은 다음과 같습니다.
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
추가 정보를 반환하려면 필드 마스크에 데이터 유형을 더 추가하세요.
예를 들어 places.formattedAddress,places.types,places.websiteUri
를 추가하여
식당 주소, 유형 및 웹 주소를 응답으로 표시합니다.
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \ https://places.googleapis.com/v1/places:searchNearby
응답 이(가) 다음과 같은 형식으로 되었습니다.
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
여러 유형의 장소 찾기
다음 예는
반경 1,000미터 이내에 있는 모든 편의점과 주류 판매점의 이름을
지정된 circle
:
curl -X POST -d '{ "includedTypes": ["liquor_store", "convenience_store"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \ https://places.googleapis.com/v1/places:searchNearby이 예시에서는
places.primaryType
및 places.types
를 필드 마스크에 추가합니다.
이렇게 하면 응답에 각 장소에 대한 유형 정보가 포함되어
적절한 위치를 찾을 수 있습니다.
검색에서 장소 유형 제외
다음 예는 모든 장소에 대한 주변 검색 (신규) 요청을 보여줍니다.
"school"
유형, "primary_school"
유형의 모든 장소 제외, 결과 순위 지정
거리별:
curl -X POST -d '{ "includedTypes": ["school"], "excludedTypes": ["primary_school"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } }, "rankPreference": "DISTANCE" }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
거리별 순위로 지역 근처의 모든 장소 검색
다음 예는 장소에 대한 주변 검색 (신규) 요청을 보여줍니다.
샌프란시스코 시내의 한 지점 근처에서 말이죠. 이 예에서는 rankPreference
매개변수를 사용하여 거리별로 결과의 순위를 지정할 수 있습니다.
curl -X POST -d '{ "maxResultCount": 10, "rankPreference": "DISTANCE", "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
사용해 보기
API 탐색기를 사용하면 샘플 요청을 수행하여 API 및 API 옵션에 익숙해지실 수 있습니다.
- API 아이콘
을 선택합니다. 을 클릭합니다.
- 필요한 경우 표준 매개변수 표시를 펼치고
fields
매개변수 필드 마스크에 추가합니다. - 필요한 경우 요청 본문을 수정합니다.
- 실행 버튼을 선택합니다. 팝업에서 요청에 사용할 계정을 선택합니다.
API 탐색기 패널에서 펼치기 아이콘을 선택합니다.
: API 탐색기 창을 펼칩니다.