주변 검색 (신규)

플랫폼 선택: Android iOS JavaScript 웹 서비스
유럽 경제 지역 (EEA) 개발자

소개

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

API 탐색기를 사용하면 API와 API 옵션을 익힐 수 있도록 라이브 요청을 할 수 있습니다.

대화형 데모를 사용해 지도에 표시되는 주변 지역 검색 (New) 결과를 확인해 보세요.

주변 지역 검색 (신규) 요청

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

주변 지역 검색 (신규) 응답

주변 지역 검색 (신규)는 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: *

    다음 필드 중 하나 이상을 지정합니다.

    • 다음 필드는 주변 지역 검색 Pro SKU를 트리거합니다.

      places.accessibilityOptions
      places.addressComponents
      places.addressDescriptor*
      places.adrFormatAddress
      places.attributions
      places.businessStatus
      places.consumerAlert
      places.containingPlaces
      places.displayName
      places.formattedAddress
      places.googleMapsLinks
      places.googleMapsTypeLabel
      places.googleMapsUri
      places.iconBackgroundColor
      places.iconMaskBaseUri
      places.id
      places.location
      places.name**
      places.movedPlace
      places.movedPlaceId
      places.openingDate
      places.photos
      places.plusCode
      places.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.subDestinations
      places.timeZone
      places.types
      places.utcOffsetMinutes
      places.viewport

      * 주소 설명자는 일반적으로 인도 고객에게 제공되며 다른 지역에서는 실험적으로 제공됩니다.

      ** places.name 필드에 리소스 이름 장소가 places/PLACE_ID 형식으로 포함됩니다. places.displayName을 사용하여 장소의 텍스트 이름에 액세스합니다.

      필드와 연결된 SKU의 전체 목록은 장소 데이터 필드 (신규)를 참고하세요.

    • 다음 필드는 주변 지역 검색 Enterprise SKU를 트리거합니다.

      places.currentOpeningHours
      places.currentSecondaryOpeningHours
      places.internationalPhoneNumber
      places.nationalPhoneNumber
      places.priceLevel
      places.priceRange
      places.rating
      places.regularOpeningHours
      places.regularSecondaryOpeningHours
      places.transitStation
      places.userRatingCount
      places.websiteUri

      필드와 연결된 SKU의 전체 목록은 장소 데이터 필드 (신규)를 참고하세요.

    • 다음 필드는 주변 지역 검색 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
      routingSummaries*
      places.servesBeer
      places.servesBreakfast
      places.servesBrunch
      places.servesCocktails
      places.servesCoffee
      places.servesDessert
      places.servesDinner
      places.servesLunch
      places.servesVegetarianFood
      places.servesWine
      places.takeout

      * 텍스트 검색 및 주변 검색만 해당

      필드와 연결된 SKU의 전체 목록은 장소 데이터 필드 (신규)를 참고하세요.

  • locationRestriction

    검색할 지역이 원으로 지정됩니다. 원은 중심점과 반지름(미터)으로 정의됩니다. 반경은 0.0 이상 50000.0 이하여야 합니다. 기본 반경은 0.0입니다. 요청에서 0.0보다 큰 값으로 설정해야 합니다.

    예를 들면 다음과 같습니다. 

    "locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

선택적 매개변수

  • includeFutureOpeningBusinesses

    true인 경우 향후 개업할 것으로 예상되는 비즈니스를 반환합니다. 기본값은 false입니다.

    비즈니스 상태를 가져오려면 요청 필드 마스크에 places.businessStatus를 포함하세요. 비즈니스의 예상 개업일을 가져오려면 요청 필드 마스크에 places.openingDate를 포함하세요.

  • includedTypes/excludedTypes, includedPrimaryTypes/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

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

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

    대부분의 CLDR 코드는 ISO 3166-1 코드와 동일하지만 일부 주목할 만한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)이지만 ISO 3166-1 코드는 'gb' (엄밀히 말해 '그레이트브리튼 북아일랜드 연합왕국'의 법인)입니다. 이 매개변수는 관련 법규에 따라 결과에 영향을 미칠 수 있습니다.

주변 지역 검색 (신규) 예

한 유형의 장소 찾기

다음 예는 circle로 정의된 500미터 반경 내에 있는 모든 음식점의 표시 이름을 요청하는 주변 지역 검색 (New) 요청을 보여줍니다. 

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,000m 이내에 있는 모든 편의점과 주류 판매점의 표시 이름에 대한 주변 지역 검색 (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" 유형의 모든 장소에 대한 주변 지역 검색 (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

지역 근처의 모든 장소를 검색하고 거리를 기준으로 순위를 지정합니다.

다음 예는 샌프란시스코 시내의 한 지점 근처에 있는 장소에 대한 주변 지역 검색 (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

주소 설명자 가져오기

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

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

curl -X POST -d '{
  "maxResultCount": 5,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      },"radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"],
  "excludedTypes": [],
  "rankPreference":"POPULARITY"
}' \
-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:searchNearby

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

  {
    "places": [
      {
        "displayName": {
          "text": "Westfield Valley Fair",
          "languageCode": "en"
        },
        "addressDescriptor": {
          "landmarks": [
            {
              "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": 114.76984,
              "travelDistanceMeters": 114.261856
            },
            {
              "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "displayName": {
                "text": "Valley Fair Mall Eyexam of CA",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "health",
                "point_of_interest"
              ],
              "straightLineDistanceMeters": 131.62566,
              "travelDistanceMeters": 237.33253
            },
            {
              "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "displayName": {
                "text": "Din Tai Fung",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "food",
                "point_of_interest",
                "restaurant"
              ],
              "straightLineDistanceMeters": 110.0775,
              "travelDistanceMeters": 171.41951
            },
            {
              "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "displayName": {
                "text": "Abercrombie & Fitch",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 53.620117,
              "travelDistanceMeters": 2.4578214
            },
            {
              "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "displayName": {
                "text": "Hollister Co.",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 56.53726,
              "travelDistanceMeters": 15.418246
            }
          ],
          "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": "OUTSKIRTS"
            }
          ]
        }
      },
  /.../
  }

향후 개업 예정인 비즈니스 찾기

다음 예는 아이다호주 뉴메도우즈에서 향후 개업하는 비즈니스에 대한 주변 지역 검색 (New) 요청을 보여줍니다.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.openingDate" \
-d '{
  "includeFutureOpeningBusinesses": true,
  "maxResultCount": 20,
  "locationRestriction": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  },
  "rankPreference": "DISTANCE"
}' \
"https://places.googleapis.com/v1/places:searchNearby"

대답에는 향후 개업할 비즈니스와 비즈니스 상태, 예상 개업일이 포함됩니다.

{
  "places": [
    {
      "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
      "businessStatus": "FUTURE_OPENING",
      "displayName": {
        "text": "Roberts Greenhouse and Tree Farm",
        "languageCode": "en"
      },
      "openingDate": {
        "year": 2026,
        "month": 4,
        "day": 15
      }
    }
  ]
}

대중교통 역 정보 가져오기

주변 지역 검색 (신규)을 사용하여 특정 위치의 지정된 반경 내에 있는 역/정류장에 관한 정보를 확인할 수 있습니다. 응답 본문에는 역 이름, 소속 대중교통 기관, 역을 운행하는 대중교통 노선 등 역에 관한 정보가 포함됩니다. 또한 대중교통역 정보를 표시하는 데 사용할 수 있는 차량 아이콘과 색상이 응답에 포함됩니다.

다음 예는 맨해튼 미드타운에서 50미터 이내의 대중교통 역에 대한 요청을 보여줍니다.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.transitStation" \
-d '{
  "includedTypes": ["transit_station"],
  "locationRestriction": {
    "circle": {
      "center": {"latitude": 40.754851, "longitude": -73.984164},
      "radius": 50.0
    }
  }
}' \
"https://places.googleapis.com/v1/places:searchNearby"

응답 본문에는 반경 내 각 역에 관한 정보, 역에서 운행하는 노선, 해당 정류장에서 대중교통 기관이 발행한 알림, 출발 정보가 포함됩니다.

{
  "places": [
    {
      "id": "ChIJH2EstKpZwokRCwZtYyMd5Fg",
      "displayName": {
        "text": "6 Av/W 41 St",
        "languageCode": "en"
      },
      "transitStation": {
        "displayName": {
          "text": "6 Av/W 41 St",
          "languageCode": "en"
        },
        "agencies": [
          {
            "displayName": {
              "text": "ShortLine Hudson",
              "languageCode": "en"
            },
            "url": "https://www.coachusa.com/",
            "lines": [
              {
                "id": "ChIJSQlbzvPwwokRolrIA-Kuh6o",
                "vehicleType": "BUS",
                "displayName": {
                  "text": "200 - Northern District – Nanuet",
                  "languageCode": "en"
                },
                "shortDisplayName": {
                  "text": "ShortLine Hudson",
                  "languageCode": "en"
                },
                "textColor": "#000000",
                "backgroundColor": "#ED60A3",
                "vehicleIcon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg"
                }
              }
            ]
          },
          {
            "displayName": {
              "text": "MTA New York City Transit",
              "languageCode": "en"
            },
            "url": "http://www.mta.info/",
            "lines": [
              {
                "id": "ChIJjUrj7PBewokR3O3S2JVpBrI",
                "vehicleType": "SUBWAY",
                "displayName": {
                  "text": "E Train (8 Av Local)",
                  "languageCode": "en"
                },
                "shortDisplayName": {
                  "text": "E Line",
                  "languageCode": "en"
                },
                "textColor": "#FFFFFF",
                "backgroundColor": "#0039A6",
                "url": "https://www.mta.info/schedules/subway/e-train",
                "icon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/E.svg",
                  "nameIncluded": true
                },
                "vehicleIcon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg"
                }
              },
              ...
            ]
          },
        "stops": [
          {
            "id": "ChIJvRnquapZwokRdUOyVwNGbe8",
            "displayName": {
              "text": "6 Av/W 41 St",
              "languageCode": "en"
            },
            "location": {
              "latitude": 40.754509,
              "longitude": -73.984216500000016
            },
            "wheelchairAccessibleEntrance": true
          }
        ],
        "departureBoards": [
          {
            "displayType": "DIRECTION_CENTRIC",
            "rows": [
              {
                "departures": [
                  {
                    "timedDeparture": {
                      "scheduledTime": "2026-05-15T22:29:51Z",
                      "timingType": "SCHEDULED"
                    },
                    "originallyScheduledStopId": "ChIJvRnquapZwokRdUOyVwNGbe8",
                    "lineId": "ChIJA1aFyaZfwokRkO5869M6UXk"
                  }
                ]
              },
              {
                "departures": [
                  {
                    "timedDeparture": {
                      "scheduledTime": "2026-05-15T22:33:55Z",
                      "timingType": "SCHEDULED"
                    },
                    "originallyScheduledStopId": "ChIJvRnquapZwokRdUOyVwNGbe8",
                    "lineId": "ChIJj3iCEwJfwokRZE2Qtnm4pPI"
                  }
                ]
              },
              ...
            ]
          }
        ]
      }
    },
    ...
    {
      {
        "id": "ChIJPyq6TZBZwokRdGoiJ5Iq_hE",
        "vehicleType": "BUS",
        "displayName": {
          "text": "W 44 St - South Ferry",
          "languageCode": "en"
        },
        "shortDisplayName": {
          "text": "M55",
          "languageCode": "en"
        },
        "textColor": "#FFFFFF",
        "backgroundColor": "#1D59B3",
        "vehicleIcon": {
          "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg"
        },
        "alerts": [
          {
            "effect": "OTHER",
            "texts": [
              {
                "headline": {
                  "text": "Information",
                  "languageCode": "en"
                },
                "summary": {
                  "text": "Northbound M20 and M55 stop on State St at Bridge St is closed; use the temporary stop on State St before the intersection instead",
                  "languageCode": "en"
                },
                "fullDescription": {
                  "text": "See a map of the new stop location. What's happening? Construction",
                  "languageCode": "en"
                }
              }
            ],
            "detailsUrls": [
              {
                "url": "https://www.mta.info/"
              }
            ],
            "cause": "OTHER_CAUSE",
            "startTime": "2025-04-02T04:00:00Z",
            "endTime": "2026-06-15T00:00:00Z",
            "attribution": {
              "link": {
                "text": "www.mta.info",
                "url": "https://www.mta.info/"
              }
            },
            "createTime": "2026-05-15T22:32:00Z",
            "severityLevel": "INFO"
          }
        ]
      },
      ...
    }
    ...
  }

입구 및 탐색 지점 가져오기

목적지의 출입구와 탐색 지점을 요청할 수 있습니다. 입구는 장소의 출입구를 정의합니다 (예: 공항이나 쇼핑몰의 여러 게이트). 탐색 지점은 탐색이 종료되어야 하는 도로변 위치를 정의하며, 이는 사용자를 올바른 도로변이나 특정 하차 지점으로 안내하는 데 유용합니다.

탐색 포인트는 navigationPointToken를 반환합니다. 이 토큰을 Navigation SDK (Android 또는 iOS에서 사용 가능) 또는 Routes API에 전달하여 운전자를 해당 특정 위치로 안내할 수 있습니다. 자세한 내용은 탐색 지점 토큰을 참고하세요.

다음 예는 필드 마스크에 entrances 및 navigationPoints가 포함된 주변 지역 검색 (New) 요청을 보여줍니다.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.entrances,places.navigationPoints" \
-d '{
  "includedTypes": ["airport"],
  "maxResultCount": 1,
  "locationRestriction": {
    "circle": {
      "center": {"latitude": 37.6193, "longitude": -122.3816},
      "radius": 1000.0
    }
  }
}' \
"https://places.googleapis.com/v1/places:searchNearby"

대답에는 장소의 출입구와 탐색 지점이 포함됩니다.

{
  "places": [
    {
      "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ",
      "displayName": {
        "text": "San Francisco International Airport",
        "languageCode": "en"
      },
      "entrances": [
        {
          "location": {
            "latitude": 37.6172154,
            "longitude": -122.3839724
          }
        },
        {
          "location": {
            "latitude": 37.6174073,
            "longitude": -122.384196
          }
        },
        ...
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...",
          "displayName": {
            "text": "International Terminal Departures Level",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6153121,
            "longitude": -122.3900833
          },
          "travelModes": ["WALK"]
        },
        {
          "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...",
          "displayName": {
            "text": "Domestic Garage - SFO Short Term Parking",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6157153,
            "longitude": -122.3885012
          },
          "travelModes": ["DRIVE", "WALK"],
          "usages": ["PARKING"]
        },
        ...
      ]
    }
  ]
}

기능을 사용해 보세요.

API 탐색기를 사용하면 샘플 요청을 만들어 API와 API 옵션에 익숙해질 수 있습니다.

  1. 페이지 오른쪽에 있는 API 아이콘 api을 선택합니다.

  2. 원하는 경우 요청 매개변수를 수정합니다.

  3. 실행 버튼을 선택합니다. 대화상자에서 요청을 보낼 때 사용할 계정을 선택합니다.

  4. API 탐색기 패널에서 전체 화면 아이콘 fullscreen을 선택하여 API 탐색기 창을 펼칩니다.