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

주변 검색 (신규)

주변 검색 (신규) 요청은 하나 이상의 장소 유형을 가져와 지정된 지역 내에서 일치하는 장소 목록을 반환합니다. 하나 이상의 데이터 유형을 지정하는 필드 마스크가 필요합니다. 주변 검색 (신규)은 POST 요청만 지원합니다.

API 탐색기를 사용하면 실시간 요청을 수행하여 API 및 API 옵션에 익숙해질 수 있습니다.

실습

주변 검색 (신규) 요청

Nearby Search (New) 요청은 다음 형식의 URL에 관한 HTTP POST 요청입니다.

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

주변 검색 (신규) 응답

Nearby Search (신규)는 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 사용에 관한 자세한 내용은 장소 아이콘 섹션을 참고하세요.

다음 필드 중 하나 이상을 지정합니다.
- 다음 필드는 Nearby Search (Basic) SKU를 트리거합니다.
  
  places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, 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.restroom, places.reviews, places.restroom, places.reviews, places.delivery{2, places.delivery, places.delivery, places.delivery, places.delivery, places.delivery, places.delivery, places.outdoorSeatingplaces.reservableplaces.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.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개의 유형을 지정할 수 있습니다.

참고: 표 B의 값은 응답에서만 반환됩니다. 표 B의 값은 필터로 사용할 수 없습니다.

장소는 유형과 연결된 표 A 유형의 단일 기본 유형만 가질 수 있습니다. 예를 들어 기본 유형은 "mexican_restaurant" 또는 "steak_house"일 수 있습니다. includedPrimaryTypes 및 excludedPrimaryTypes를 사용하여 장소의 기본 유형에 대한 결과를 필터링합니다.

장소는 연결된 표 A 유형의 여러 유형 값도 가질 수 있습니다. 예를 들어 음식점의 유형은 "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment"일 수 있습니다. includedTypes 및 excludedTypes를 사용하여 장소와 연결된 유형 목록의 결과를 필터링합니다.

검색에 여러 유형의 제한사항을 지정하면 모든 제한사항을 충족하는 장소만 반환됩니다. 예를 들어 {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}를 지정하면 반환되는 장소는 "restaurant" 관련 서비스를 제공하지만 주로 "steak_house"으로 작동하지는 않습니다.

요청에서 includedTypes, excludedTypes, includedPrimaryTypes, excludedPrimaryTypes를 생략하면 위치 제한 경계 내에서 모든 유형의 장소가 반환됩니다.

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

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

반환할 장소 결과의 최대 개수를 지정합니다. 1 이상, 20 이하여야 합니다 (기본값).
rankPreference

사용할 순위 유형입니다. 이 매개변수를 생략하면 인기도에 따라 검색 결과가 순위가 매겨집니다. 다음 중 하나일 수 있습니다.
- POPULARITY (기본값): 인기도에 따라 결과를 정렬합니다.
- DISTANCE 지정된 위치로부터의 거리를 기준으로 결과를 오름차순으로 정렬합니다.
regionCode

응답 형식을 지정하는 데 사용되는 리전 코드로, 2자리 CLDR 코드 값으로 지정됩니다. 기본값은 없습니다.

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

대부분의 CLDR 코드는 ISO 3166-1 코드와 동일하지만 일부 특별한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)인 반면 ISO 3166-1 코드는 'gb' (기술적으로 '영국 및 북아일랜드'의 엔티티)입니다. 매개변수는 관련 법률에 따라 결과에 영향을 줄 수 있습니다.

주변 검색 (신규) 예시

한 유형의 장소 찾기

다음 예는 반경 500미터 이내에 있는 모든 음식점의 표시 이름에 관한 Nearby Search (New) 요청을 보여주며, 이는 circle로 정의됩니다.

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"
      }
    },
...
}

여러 유형의 장소 찾기

다음 예는 지정된 circle의 반경 1,000미터 이내에 있는 모든 편의점과 주류 매장의 표시 이름을 위한 Nearby Search (New) 요청을 보여줍니다.

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를 추가하여 응답에 각 장소에 대한 유형 정보가 포함되도록 하여 결과에서 적절한 장소를 더 쉽게 선택할 수 있도록 합니다.

검색에서 장소 유형 제외

다음 예는 "primary_school" 유형의 모든 장소를 제외하고 "school" 유형의 모든 장소에 대한 Nearby Search (New) 요청을 보여주며 거리별로 검색 결과의 순위를 매깁니다.

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

특정 지역 주변의 모든 장소 검색(거리별 순위)

다음 예는 샌프란시스코 시내의 특정 지점 근처 장소에 대한 Nearby Search (New) 요청을 보여줍니다. 이 예에서는 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 탐색기 창을 펼칩니다.

주변 검색 (신규)

주변 검색 (신규) 요청

주변 검색 (신규) 응답

필수 매개변수

FieldMask

locationRestriction

선택적 매개변수

includeTypes/excludedTypes, IncludePrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode