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

텍스트 검색(신규)

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

유럽 경제 지역 (EEA) 개발자

소개

텍스트 검색(신규)은 문자열(예: '뉴욕의 피자', '오타와 근처의 신발 가게' 또는 '중앙로 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'이 하나만 있고 미국 플레즌턴에는 'Main Street'이 하나만 있습니다.
'UniqueRestaurantName New York'	뉴욕에 이 이름의 업체가 하나만 있으므로 구분하는 데 번지 주소가 필요하지 않습니다.
'뉴욕 피자 레스토랑'	이 쿼리에는 위치 제한이 포함되어 있으며 '피자 전문점'은 잘 정의된 장소 유형입니다. 여러 결과를 반환합니다.
'+1 514-670-8700'	이 쿼리에는 전화번호가 포함되어 있습니다. 이 경우 해당 전화번호와 연결된 장소에 대한 결과가 여러 개 반환됩니다. 참고: 전화번호를 검색할 때 최상의 결과를 얻으려면 국가 코드를 포함하고 공백을 추가한 후 `regionCode` 매개변수를 국가 코드에 맞게 설정하세요. 전화번호 형식은 국가마다 다르며 API는 이러한 다양한 형식의 결과를 반환하려고 시도합니다.

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 Essentials ID Only SKU를 트리거합니다.
  places.attributions
  places.id
  places.name^*
  nextPageToken
  
  ^* places.name 필드에는 장소 리소스 이름이 places/PLACE_ID 형식으로 포함됩니다. Pro SKU에서 places.displayName을 사용하여 장소의 텍스트 이름에 액세스합니다.
- 다음 필드는 Text Search Pro SKU를 트리거합니다.
  places.accessibilityOptions
  places.addressComponents
  places.addressDescriptor^*
  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.postalAddress
  places.primaryType
  places.primaryTypeDisplayName
  places.pureServiceAreaBusiness
  places.shortFormattedAddress
  places.subDestinations
  places.types
  places.utcOffsetMinutes
  places.viewport
  
  ^* 주소 설명자는 일반적으로 인도 고객에게 제공되며 다른 지역에서는 실험용으로 제공됩니다.
  
  ^** places.googleMapsLinks 필드는 GA 전 미리보기 단계에 있으며 미리보기 기간 동안의 사용량에 대한 요금이 청구되지 않습니다(청구액이 $0임).
- 다음 필드는 Text Search Enterprise 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 Enterprise + Atmosphere SKU를 트리거합니다.
  places.allowsDogs
  places.curbsidePickup
  places.delivery
  places.dineIn
  places.editorialSummary
  places.evChargeAmenitySummary
  places.evChargeOptions
  places.fuelOptions
  places.generativeSummary
  places.goodForChildren
  places.goodForGroups
  places.goodForWatchingSports
  places.liveMusic
  places.menuForChildren
  places.neighborhoodSummary
  places.parkingOptions
  places.paymentOptions
  places.outdoorSeating
  places.reservable
  places.restroom
  places.reviews
  places.reviewSummary
  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의 값을 필터로 사용할 수 없습니다.

텍스트 검색 (신규)은 적용 가능성에 따라 특정 쿼리에 유형 필터링을 적용합니다. 예를 들어 특정 주소 ('123 Main Street')에 대한 쿼리에는 유형 필터링이 적용되지 않을 수 있지만, 카테고리별 쿼리 ('근처 매장' 또는 '쇼핑몰')에는 유형 필터링이 거의 항상 적용됩니다.

모든 쿼리에 유형 필터링을 적용하려면 strictTypeFiltering을 true로 설정합니다.
includePureServiceAreaBusinesses

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

결과를 반환할 언어입니다.
- 지원되는 언어 목록을 참고하세요. Google에서는 지원되는 언어를 자주 업데이트하므로 이 목록에 모든 언어가 포함되지 않을 수도 있습니다.
- languageCode가 제공되지 않으면 API는 기본적으로 en을 사용합니다. 잘못된 언어 코드를 지정하면 API에서 INVALID_ARGUMENT 오류를 반환합니다.
- 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

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

리전을 직사각형 뷰포트로 지정합니다. Viewport 정의의 예는 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
  
  장소에서 사용할 수 있는 EV 충전 커넥터 유형을 기준으로 필터링합니다. 커넥터 유형을 지원하지 않는 장소는 필터링됩니다. 지원되는 EV 충전 커넥터 유형에는 결합형 (AC 및 DC) 충전기, Tesla 충전기, GB/T 규격 충전기 (중국의 EV 급속 충전용), 벽면 콘센트 충전기가 포함됩니다. 자세한 내용은 참조 문서를 확인하세요.
  - 지원되는 특정 커넥터의 결과를 필터링하려면 connectorTypes을 해당 값으로 설정합니다. 예를 들어 J1772 유형 1 커넥터를 찾으려면 connectorTypes을 EV_CONNECTOR_TYPE_J1772로 설정합니다.
  - 지원되지 않는 커넥터의 결과를 필터링하려면 connectorTypes를 EV_CONNECTOR_TYPE_OTHER로 설정합니다.
  - 벽면 콘센트인 커넥터 유형의 결과를 필터링하려면 connectorTypes을 EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET로 설정합니다.
  - 커넥터 유형의 결과를 필터링하려면 connectorTypes을 EV_CONNECTOR_TYPE_UNSPECIFIED로 설정하거나 connectorTypes 값을 설정하지 않습니다.
- 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 지역 정보 데이터베이스에 영업시간을 지정하지 않은 장소가 반환됩니다.
pageSize

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

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

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

특정 가격대로 표시된 장소로 검색을 제한합니다. 기본적으로 모든 가격대가 선택됩니다.

다음 유형의 장소에는 가격대가 표시될 수 있습니다.
priceLevels가 지정된 경우 지원되지 않는 유형의 장소는 응답에 포함되지 않습니다.

PriceLevel에 의해 정의된 하나 이상의 값으로 이루어진 배열을 지정합니다.

예를 들면 다음과 같습니다.
```
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
```
참고: PRICE_LEVEL_FREE는 요청에서 허용되지 않습니다. 대답을 채우는 데만 사용됩니다.
rankPreference

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

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

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

대부분의 CLDR 코드는 ISO 3166-1 코드와 동일하지만 일부 주목할 만한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)이지만 ISO 3166-1 코드는 'gb' (기술적으로 '영국' 법인의 경우)입니다. 이 매개변수는 관련 법규에 따라 결과에 영향을 미칠 수 있습니다.
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 데이터 필드를 response에 추가하므로 다음과 같은 형식이 됩니다.

{
  "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를 사용하여 특정 지역으로 편향

다음 예에서는 샌프란시스코 시내의 한 지점에서 500m 이내의 위치로 편향된 '채식 음식'에 대한 텍스트 검색 (신규) 요청을 보여줍니다. 이 요청은 영업 중인 장소의 처음 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"
}

주소 설명자 가져오기

주소 설명자는 주변 명소와 포함된 지역을 비롯한 장소의 위치에 관한 관계형 정보를 제공합니다.

다음 예는 산호세의 쇼핑몰 근처에 있는 장소에 대한 텍스트 검색 (신규) 요청을 보여줍니다. 이 예에서는 필드 마스크에 addressDescriptors를 포함합니다.

curl -X POST -d '{
  "textQuery": "clothes",
  "maxResultCount": 5,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      }
    }
  },
  "rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchText

응답에는 요청에 지정된 장소, 근처 랜드마크 목록과 장소와의 거리, 지역 목록과 장소와의 포함 관계가 포함됩니다.

  {
  "places": [
    {
      "displayName": {
        "text": "Urban Outfitters",
        "languageCode": "en"
      },
      "addressDescriptor": {
        "landmarks": [
          {
            "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "food",
              "movie_theater",
              "point_of_interest",
              "restaurant",
              "shoe_store",
              "shopping_mall",
              "store"
            ],
            "spatialRelationship": "WITHIN",
            "straightLineDistanceMeters": 133.72855
          },
          {
            "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "displayName": {
              "text": "Nordstrom",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 250.99161
          },
          {
            "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "placeId": "ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "displayName": {
              "text": "Macy's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "store"
            ],
            "straightLineDistanceMeters": 116.24196
          },
          {
            "name": "places/ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "placeId": "ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "displayName": {
              "text": "Bank of America Financial Center",
              "languageCode": "en"
            },
            "types": [
              "bank",
              "establishment",
              "finance",
              "point_of_interest"
            ],
            "straightLineDistanceMeters": 121.61515
          },
          {
            "name": "places/ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "placeId": "ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "displayName": {
              "text": "Bloomingdale's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "furniture_store",
              "home_goods_store",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 81.32396
          }
        ],
        "areas": [
          {
            "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "displayName": {
              "text": "Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "displayName": {
              "text": "Central San Jose",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          }
        ]
      }
    },
    /.../
  ]
}

사용해 보기

API 탐색기를 사용하면 API 및 API 옵션에 익숙해질 수 있도록 샘플 요청을 할 수 있습니다.

페이지 오른쪽에 있는 API 아이콘 api을 선택합니다.
원하는 경우 요청 매개변수를 수정합니다.
실행 버튼을 선택합니다. 대화상자에서 요청을 보낼 때 사용할 계정을 선택합니다.
API 탐색기 패널에서 전체 화면 아이콘 전체 화면을 선택하여 API 탐색기 창을 펼칩니다.

텍스트 검색(신규)

소개

텍스트 검색 (신규) 요청

텍스트 검색 (신규) 응답

필수 매개변수

FieldMask

textQuery

선택적 매개변수

includedType

includePureServiceAreaBusinesses

languageCode

locationBias

locationRestriction

maxResultCount (지원 중단됨)

evOptions

connectorTypes

minimumChargingRateKw

minRating

openNow

pageSize

pageToken

priceLevels

rankPreference

regionCode

strictTypeFiltering

텍스트 검색 (신규) 예시

쿼리 문자열로 장소 찾기

가격대로 장소 필터링

지정된 지역으로 검색 제한

locationRestriction을 사용하여 영역 제한

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

최소 충전 속도로 전기자동차 충전기 검색

서비스 지역 비즈니스 검색

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

주소 설명자 가져오기

사용해 보기