이 페이지는 Cloud Translation API를 통해 번역되었습니다.

텍스트 검색(신규)

플랫폼 선택: Android iOS JavaScript 웹 서비스

텍스트 검색(신규)은 문자열(예: '뉴욕의 피자', '오타와 근처의 신발 가게' 또는 '중앙로 123')을 기반으로 일련의 장소에 대한 정보를 반환하는 웹 서비스입니다. 이 서비스는 텍스트 문자열 및 설정된 위치 편중과 일치하는 장소 목록을 반환합니다.

이 서비스는 자동화된 시스템에서 모호한 주소 쿼리를 할 때 특히 유용하며, 문자열에서 주소가 아닌 구성 요소는 사업체 및 주소와 일치할 수 있습니다. 예를 들어, 모호한 주소 쿼리는 형식이 잘못된 주소 또는 비즈니스 이름과 같이 주소가 아닌 구성 요소가 포함된 요청 등이 있습니다. 다음 표의 처음 두 예와 같은 요청은 지역, 위치 제한 또는 위치 편향과 같은 위치가 설정되지 않는 한 결과를 반환하지 않을 수 있습니다.

'10 High Street, UK' 또는 '123 Main Street, US'	영국의 여러 'High Street', 미국의 여러 'Main Street' 위치 제한을 설정하지 않으면 쿼리에서 원하는 결과를 반환하지 않습니다.
'ChainRestaurant New York'	뉴욕에 여러 개의 'ChainRestaurant' 위치가 있지만 상세 주소나 도로 이름이 없습니다.
'10 High Street, Escher UK' 또는 '123 Main Street, Pleasanton US'	영국 에셔 시에는 'High Street'가 1개만 있고, 미국 캘리포니아 주 플레젠튼 시에는 'Main Street'가 1개만 있습니다.
"UniqueRestaurantName New York"	뉴욕에 이 이름의 시설이 하나만 있습니다. 구분하는 데 필요한 상세 주소가 없습니다.
"뉴욕 피자 레스토랑"	이 쿼리에는 위치 제한이 포함되어 있으며 '피자 전문점'은 잘 정의된 장소 유형입니다. 여러 결과를 반환합니다.
'+1 514-670-8700'	이 쿼리에는 전화번호가 포함되어 있습니다. 이 전화번호와 연결된 장소에 대한 여러 결과를 반환합니다. 참고: 전화번호를 검색할 때 최상의 결과를 얻으려면 국가 코드 뒤에 공백을 넣고 `regionCode` 매개변수를 국가 코드에 맞게 설정하세요.

API 탐색기를 사용하면 API 및 API 옵션을 숙지할 수 있도록 실시간 요청을 할 수 있습니다.

사용해 보기

텍스트 검색 요청

텍스트 검색 요청은 다음 형식의 HTTP POST 요청입니다.

https://places.googleapis.com/v1/places:searchText

JSON 요청 본문 또는 헤더의 모든 매개변수를 POST 요청의 일부로 전달합니다. 예를 들면 다음과 같습니다.

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

텍스트 검색 (신규) 응답

텍스트 검색 (신규)은 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: *
```
와일드 카드 '*'은 모든 필드를 선택합니다. 그러나 이 와일드 카드는 개발 시에는 사용할 수 있지만 반환될 수 있는 데이터의 양이 많기 때문에 프로덕션에서는 와일드 카드 (*) 응답 필드 마스크를 사용하지 않는 것이 좋습니다.

places.iconMaskBaseUri 및 places.iconBackgroundColor 사용에 관한 자세한 안내는 장소 아이콘 섹션을 참고하세요.

다음 필드 중 하나 이상을 지정합니다.
- 다음 필드는 Text Search (ID Only) SKU를 트리거합니다.
  places.attributions, places.id, places.name^*, nextPageToken
  
  ^* places.name 필드에 리소스 이름 장소가 places/PLACE_ID 형식으로 포함됩니다. places.displayName을 사용하여 장소의 텍스트 이름에 액세스합니다.
- 다음 필드는 Text Search (Basic) SKU를 트리거합니다.
  places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.containingPlaces, places.displayName, places.formattedAddress, places.googleMapsLinks^*, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.location, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.pureServiceAreaBusiness, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport
  
  ^* places.googleMapsLinks 필드는 GA 이전 미리보기 단계에 있으며 요금이 청구되지 않으므로 미리보기 기간 동안 사용 시 청구 금액은 0달러입니다.
- 다음 필드는 Text Search (Advanced) SKU를 트리거합니다.
  places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.priceRange, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri
- 다음 필드는 Text 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.routingSummaries,^* places.servesBeer, places.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.takeout
  
  ^* 텍스트 검색 및 주변 검색만 해당
textQuery

검색할 텍스트 문자열입니다(예: '식당', '중앙로 123', '샌프란시스코에서 가볼 만한 곳'). API는 이 문자열을 기반으로 일치 가능성이 있는 항목을 반환하고 감지된 관련성을 기반으로 검색 결과를 정렬합니다.

선택적 매개변수

includedType

표 A에 정의된 지정된 유형과 일치하는 장소로 결과를 제한합니다. 유형은 하나만 지정할 수 있습니다. 예를 들면 다음과 같습니다.
- "includedType":"bar"
- "includedType":"pharmacy"
참고: 표 B의 값은 응답에서만 반환됩니다. 표 B의 값을 필터로 사용할 수 없습니다.
includePureServiceAreaBusinesses

true로 설정하면 고객을 직접 방문하거나 고객에게 직접 배송하지만 실제 비즈니스 위치가 없는 비즈니스가 응답에 포함됩니다. false로 설정하면 API는 실제 비즈니스 위치가 있는 비즈니스만 반환합니다.
languageCode

결과를 반환할 언어입니다.
- 지원되는 언어 목록을 참고하세요. 지원되는 언어는 자주 업데이트되므로 목록이 완전하지 않을 수 있습니다.
- languageCode가 제공되지 않으면 API는 기본적으로 en로 설정됩니다. 잘못된 언어 코드를 지정하면 API에서 INVALID_ARGUMENT 오류를 반환합니다.
- API는 사용자와 현지인이 모두 읽을 수 있는 거리 주소를 제공하려고 최선을 다합니다. 이를 위해 API는 기본 언어를 준수하면서 필요한 경우 사용자가 읽을 수 있는 스크립트로 음차한 현지 언어로 거리 주소를 반환합니다. 다른 모든 주소는 기본 언어로 반환됩니다. 주소 구성요소는 모두 첫 번째 구성요소에서 선택한 동일한 언어로 반환됩니다.
- 기본 언어로 이름을 사용할 수 없는 경우 API는 가장 유사한 일치 항목을 사용합니다.
- 기본 언어는 API가 반환하려고 선택한 결과 집합과 반환 순서에 약간의 영향을 미칩니다. 지오코더는 언어에 따라 유효하거나 유효하지 않을 수 있는 동의어 또는 거리 유형에 대한 약어와 같이 언어에 따라 다르게 약어를 해석합니다.
locationBias

검색할 영역을 지정합니다. 이 위치는 편향 역할을 합니다. 즉, 지정된 지역 외부의 결과를 포함하여 지정된 위치 주변의 결과가 반환될 수 있습니다.

locationRestriction 또는 locationBias 중 하나를 지정할 수 있지만 둘 다 지정할 수는 없습니다. locationRestriction는 결과가 포함되어야 하는 영역을 지정하는 것으로, locationBias는 결과가 포함되거나 근처에 있을 가능성이 높지만 해당 영역 외부에 있을 수도 있는 영역을 지정하는 것으로 생각하면 됩니다.

참고: locationBias 및 locationRestriction를 모두 생략하면 API는 기본적으로 IP 편향을 사용합니다. IP 편향의 경우 API는 기기의 IP 주소를 사용하여 결과에 편향을 적용합니다.

참고: textQuery에 Market in Barcelona와 같은 명시적 위치가 포함된 경우 locationBias 매개변수를 재정의할 수 있습니다. 이 경우 locationBias는 무시됩니다.

영역을 직사각형 표시 영역 또는 원으로 지정합니다.
- 원에는 중심점과 반지름(미터)이 정의됩니다. 반지름은 0.0 이상 50000.0 이하여야 합니다. 기본 반경은 0.0입니다. 예를 들면 다음과 같습니다.
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```
- 직사각형은 위도-경도 표시 영역으로, 대각선으로 반대되는 두 지점(최솟값 및 최댓값)으로 표시됩니다. 최저점은 직사각형의 남서쪽 모서리를 표시하고, 최고점은 직사각형의 북동쪽 모서리를 나타냅니다.
  
  표시 영역은 폐쇄된 영역으로 간주되므로 경계가 포함됩니다. 위도 경계는 -90도에서 90도 사이(양 끝값 포함)여야 하며 경도 경계는 -180도에서 180도 사이(양 끝값 포함)여야 합니다.
  - low = high이면 뷰포트는 단일 지점으로 구성됩니다.
  - low.longitude > high.longitude인 경우 경도 범위가 반전됩니다 (뷰포트가 180도 경도 선을 교차함).
  - low.longitude = -180도이고 high.longitude = 180도인 경우 뷰포트에 모든 경도가 포함됩니다.
  - low.longitude = 180도이고 high.longitude = -180도인 경우 경도 범위는 비어 있습니다.
  - low.latitude가 high.latitude보다 크면 위도 범위가 비어 있습니다.
  최솟값과 최댓값을 모두 채워야 하며, 표시된 상자는 비워 둘 수 없습니다. 뷰포트가 비어 있으면 오류가 발생합니다.
  
  예를 들어 이 뷰포트는 뉴욕시를 완전히 포함합니다.
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
locationRestriction

검색할 영역을 지정합니다. 지정된 영역 밖의 결과는 반환되지 않습니다.

영역을 직사각형 뷰포트로 지정합니다. 뷰포트를 정의하는 예는 locationBias 설명을 참고하세요.

locationRestriction 또는 locationBias 중 하나를 지정할 수 있지만 둘 다 지정할 수는 없습니다. locationRestriction는 결과가 포함되어야 하는 영역을 지정하는 것으로, locationBias는 결과가 포함되거나 근처에 있을 가능성이 높지만 해당 영역 외부에 있을 수도 있는 영역을 지정하는 것으로 생각하면 됩니다.

참고: locationBias 및 locationRestriction를 모두 생략하면 API는 기본적으로 IP 편향을 사용합니다. IP 편향의 경우 API는 기기의 IP 주소를 사용하여 결과에 편향을 적용합니다.
maxResultCount (지원 중단됨)

지원 중단됨: 이 필드는 pageSize로 대체되어 지원 중단되었습니다. maxResultCount와 pageSize가 모두 지정된 경우 pageSize가 사용되고 maxResultCount는 무시됩니다.

페이지당 표시할 결과 수 (1~20개)를 지정합니다. 예를 들어 maxResultCount 값을 5로 설정하면 첫 번째 페이지에 최대 5개의 결과가 반환됩니다. 쿼리에서 반환할 수 있는 결과가 더 있으면 응답에 후속 요청에 전달하여 다음 페이지에 액세스할 수 있는 nextPageToken가 포함됩니다.

참고: maxResultCount가 0이거나 지정되지 않은 경우 API는 기본적으로 페이지당 20개의 결과를 반환합니다. maxResultCount가 20보다 크면 API는 페이지당 20개 이하의 결과를 반환합니다.
evOptions

사용 가능한 전기자동차 (EV) 충전 커넥터 및 충전 요금을 식별하기 위한 매개변수를 지정합니다.
- connectorTypes
  
  장소에서 사용할 수 있는 전기자동차 충전소 커넥터 유형을 기준으로 필터링합니다. 커넥터 유형을 지원하지 않는 장소는 필터링됩니다. 지원되는 전기자동차 충전 커넥터 유형에는 결합형 (AC 및 DC) 충전기, 테슬라 충전기, GB/T 규격 충전기 (중국의 전기자동차 급속 충전용), 전원 콘센트 충전기가 있습니다. 자세한 내용은 참조 문서를 참고하세요.
- minimumChargingRateKw
  
  최소 전기자동차 충전 속도 (킬로와트, kW)별로 장소를 필터링합니다. 최소 충전 요금보다 낮은 요금을 적용하는 장소는 필터링됩니다. 예를 들어 충전 속도가 10kW 이상인 전기자동차 충전소를 찾으려면 이 매개변수를 '10'으로 설정하면 됩니다.
minRating

평균 사용자 평점이 이 한도보다 크거나 같은 결과로만 결과를 제한합니다. 값은 0.0~5.0 사이 (양 끝값 포함)이며 0.5 단위로 증가합니다. 예: 0, 0.5, 1.0, ... , 5.0(양 끝값 포함) 값은 가장 가까운 0.5로 반올림됩니다. 예를 들어 0.6의 값은 평점이 1.0 미만인 모든 결과를 삭제합니다.
openNow

true인 경우 쿼리가 전송된 시점에 영업 중인 장소만 반환합니다. false인 경우 영업 여부와 관계없이 모든 비즈니스를 반환합니다. 이 매개변수를 false로 설정하면 Google Places 데이터베이스에 영업시간을 지정하지 않은 장소가 반환됩니다.
pageSize

페이지당 표시할 결과 수 (1~20개)를 지정합니다. 예를 들어 pageSize 값을 5로 설정하면 첫 번째 페이지에 최대 5개의 결과가 반환됩니다. 쿼리에서 반환할 수 있는 결과가 더 있으면 응답에 후속 요청에 전달하여 다음 페이지에 액세스할 수 있는 nextPageToken가 포함됩니다.

참고: pageSize가 0이거나 지정되지 않은 경우 API는 기본적으로 페이지당 20개의 결과를 반환합니다. pageSize가 20보다 크면 API는 페이지당 20개 이하의 결과를 반환합니다.
pageToken

이전 페이지의 응답 본문에서 nextPageToken를 지정합니다.
priceLevels

특정 가격 수준으로 표시된 장소로 검색을 제한합니다. 기본값은 모든 가격대를 선택하는 것입니다.

PriceLevel로 정의된 하나 이상의 값 배열을 지정합니다.

참고: PRICE_LEVEL_FREE은 요청에서 허용되지 않습니다. 응답을 채우는 데만 사용됩니다.

예를 들면 다음과 같습니다.
```
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
```
rankPreference

검색어 유형에 따라 응답에서 결과의 순위가 지정되는 방식을 지정합니다.
- '뉴욕시 레스토랑'과 같은 카테고리 검색의 경우 기본값은 RELEVANCE (검색 관련성별 결과 순위 지정)입니다. rankPreference를 RELEVANCE 또는 DISTANCE (거리별 결과 순위 지정)로 설정할 수 있습니다.
- '캘리포니아 마운틴뷰'와 같이 카테고리가 아닌 검색어의 경우 rankPreference를 설정하지 않는 것이 좋습니다.
regionCode

응답 형식을 지정하는 데 사용되는 지역 코드로, 2자리 CLDR 코드 값으로 지정됩니다. 이 매개변수는 검색 결과에 편향 효과를 줄 수도 있습니다. 기본값은 없습니다.

응답의 formattedAddress 필드의 국가 이름이 regionCode과 일치하면 formattedAddress에서 국가 코드가 생략됩니다. 이 매개변수는 사용 가능한 경우 항상 국가 이름을 포함하는 adrFormatAddress에는 영향을 미치지 않으며, 국가 이름을 포함하지 않는 shortFormattedAddress에는 영향을 미치지 않습니다.

대부분의 CLDR 코드는 ISO 3166-1 코드와 동일하며, 몇몇 눈에 띄는 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)인 반면 ISO 3166-1 코드는 'gb'입니다(기술적으로 'Great Britain과 Northern Ireland 연방국' 엔터티). 이 매개변수는 관련 법규에 따라 결과에 영향을 줄 수 있습니다.
strictTypeFiltering

includedType 매개변수와 함께 사용됩니다. true로 설정하면 includeType로 지정된 지정된 유형과 일치하는 장소만 반환됩니다. false인 경우(기본값) 응답에 지정된 유형과 일치하지 않는 장소가 포함될 수 있습니다.

텍스트 검색 예시

쿼리 문자열로 장소 찾기

다음 예는 'Spicy Vegetarian Food in Sydney, Australia'(호주 시드니의 매운 채식 음식)에 대한 텍스트 검색 요청을 보여줍니다.

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

X-Goog-FieldMask 헤더는 응답에 places.displayName,places.formattedAddress 데이터 필드가 포함되어 있음을 지정합니다. 그러면 응답의 형식은 다음과 같습니다.

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
    ...
  ]
}

필드 마스크에 데이터 유형을 추가하여 추가 정보를 반환합니다. 예를 들어 places.types,places.websiteUri를 추가하여 응답에 음식점 유형과 웹 주소를 포함합니다.

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-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:searchText'

이제 응답의 형식은 다음과 같습니다.

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

가격대별 장소 필터링

priceLevel 옵션을 사용하여 저렴하거나 적당히 비싼 것으로 정의된 음식점으로 결과를 필터링합니다.

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

이 예에서는 X-Goog-FieldMask 헤더를 사용하여 places.priceLevel 데이터 필드를 응답에 추가하므로 다음과 같은 형식이 됩니다.

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St, Newtown NSW 2042, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

includedType, minRating, rankPreference, openNow 및 선택적 매개변수에 설명된 기타 매개변수와 같이 검색을 세분화하는 옵션을 추가합니다.

지정된 지역으로 검색 제한

locationRestriction 또는 locationBias 중 하나를 사용하여 검색 범위를 특정 지역으로 제한합니다. 둘 다 사용할 수는 없습니다. locationRestriction는 결과가 포함되어야 하는 영역을 지정하는 것으로, locationBias는 결과가 근처에 있어야 하지만 해당 영역 외부에 있을 수도 있는 영역을 지정하는 것으로 생각하면 됩니다.

참고: locationRestriction를 사용할 때는 직사각형 뷰포트로만 영역을 지정할 수 있습니다. locationBias를 사용할 때는 직사각형 뷰포트 또는 원으로 영역을 지정할 수 있습니다.

locationRestriction을 사용하여 지역 제한

locationRestriction 매개변수를 사용하여 지정된 지역으로 검색 결과를 제한합니다. 요청 본문에서 지역 경계를 정의하는 low 및 high 위도 및 경도 값을 지정합니다.

다음 예는 뉴욕시에서 '채식 음식'에 대한 텍스트 검색 요청을 보여줍니다. 이 요청은 영업 중인 장소의 처음 10개 결과만 반환합니다.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "pageSize" : "10",
  "locationRestriction": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }
}' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: API_KEY' \
  -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
  'https://places.googleapis.com/v1/places:searchText'

locationBias를 사용하여 특정 지역으로 편향

다음 예는 샌프란시스코 다운타운의 한 지점에서 500미터 이내에 있는 위치에 편향된 '채식 음식'에 대한 텍스트 검색 요청을 보여줍니다. 이 요청은 영업 중인 장소의 처음 10개 결과만 반환합니다.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "openNow": true,
  "pageSize": 10,
  "locationBias": {
    "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' \
'https://places.googleapis.com/v1/places:searchText'

최소 충전 요금이 적용되는 전기자동차 충전기 검색

minimumChargingRateKw 및 connectorTypes를 사용하여 내 전기자동차와 호환되는 충전기를 사용할 수 있는 장소를 검색합니다.

다음 예는 캘리포니아 주 마운틴뷰에 최소 충전 속도가 10kW인 Tesla 및 J1772 유형 1 EV 충전 커넥터에 대한 요청을 보여줍니다. 결과 4개만 반환됩니다.

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "pageSize": 4,
    "evOptions": {
      "minimumChargingRateKw": 10,
      "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
    }
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'

요청에 대해 다음과 같은 응답이 반환됩니다.

{
  "places": [
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 16,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 100,
            "count": 8,
            "availableCount": 5,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 2,
            "availableCount": 2,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 6,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 6,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 4,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 2,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 5,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_J1772",
            "maxChargeRateKw": 3.5999999046325684,
            "count": 1,
            "availableCount": 0,
            "outOfServiceCount": 1,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "Electric Vehicle Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 10,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_OTHER",
            "maxChargeRateKw": 210,
            "count": 10
          }
        ]
      }
    }
  ]
}

서비스 지역 비즈니스 검색

includePureServiceAreaBusinesses 매개변수를 사용하여 실제 서비스 주소가 없는 비즈니스 (예: 모바일 청소 서비스 또는 음식 트럭)를 검색합니다.

다음 예는 샌프란시스코의 배관공을 요청하는 예시입니다.

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

응답에서 실제 서비스 주소가 없는 비즈니스에는 formattedAddress 필드가 포함되지 않습니다.

{
  "places": [
    {
      "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA",
      "displayName": {
        "text": "Advanced Plumbing & Drain",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Magic Plumbing Heating & Cooling",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Cabrillo Plumbing, Heating & Air",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Mr. Rooter Plumbing of San Francisco",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Pipeline Plumbing",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA",
      "displayName": {
        "text": "One Source Plumbing and Rooter",
        "languageCode": "en"
      }
    },
    /.../
  ]
}

페이지당 반환할 결과 수 지정

pageSize 매개변수를 사용하여 페이지당 반환할 결과 수를 지정합니다. 응답 본문의 nextPageToken 매개변수는 후속 호출에서 결과의 다음 페이지에 액세스하는 데 사용할 수 있는 토큰을 제공합니다.

다음 예는 페이지당 결과 5개로 제한된 '뉴욕 피자' 요청을 보여줍니다.

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJifIePKtZwokRVZ-UdRGkZzs"
    },
    {
      "id": "ChIJPxPd_P1YwokRfzLhSiACEoU"
    },
    {
      "id": "ChIJrXXKn5NZwokR78g0ipCnY60"
    },
    {
      "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE"
    },
    {
      "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw"
    }
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

결과의 다음 페이지에 액세스하려면 pageToken를 사용하여 요청 본문에 nextPageToken를 전달합니다.

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5,
  "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw"
    },
    {
      "id": "ChIJjaD94kFZwokR-20CXqlpy_4"
    },
    {
      "id": "ChIJ6ffdpJNZwokRmcafdROM5q0"
    },
    {
      "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM"
    },
    {
      "id": "ChIJ8164qwFZwokRhplkmhvq1uE"
    }
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

사용해 보기

API 탐색기를 사용하면 샘플 요청을 실행하여 API 및 API 옵션을 익힐 수 있습니다.

페이지 오른쪽에 있는 API 아이콘 을 선택합니다.
원하는 경우 표준 매개변수 표시를 펼치고 fields 매개변수를 필드 마스크로 설정합니다.
원하는 경우 요청 본문을 수정합니다.
실행 버튼을 선택합니다. 팝업 대화상자에서 요청하는 데 사용할 계정을 선택합니다.
API 탐색기 패널에서 펼치기 아이콘 을 선택하여 API 탐색기 창을 펼칩니다.

텍스트 검색(신규)

텍스트 검색 요청

텍스트 검색 (신규) 응답

필수 매개변수

FieldMask

textQuery

선택적 매개변수

includedType

includePureServiceAreaBusinesses

languageCode

locationBias

locationRestriction

maxResultCount (지원 중단됨)

evOptions

connectorTypes

minimumChargingRateKw

minRating

openNow

pageSize

pageToken

priceLevels

rankPreference

regionCode

strictTypeFiltering

텍스트 검색 예시

쿼리 문자열로 장소 찾기

가격대별 장소 필터링

지정된 지역으로 검색 제한

locationRestriction을 사용하여 지역 제한

locationBias를 사용하여 특정 지역으로 편향

최소 충전 요금이 적용되는 전기자동차 충전기 검색

서비스 지역 비즈니스 검색

페이지당 반환할 결과 수 지정

사용해 보기