장소 세부정보 (신규)

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

소개

장소 ID가 있으면 Place Details (New) 요청을 시작하여 특정 업체 또는 관심 장소에 대한 세부정보를 요청할 수 있습니다. 장소 세부정보 (신규) 요청은 전체 주소, 전화번호, 사용자 평점 및 리뷰와 같이 지정된 장소에 대한 포괄적인 정보를 반환합니다.

장소 ID를 가져오는 방법은 다양합니다. 다음과 같은 방법을 사용할 수 있습니다.

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

장소 세부정보 (신규) 요청

장소 세부정보 (신규) 요청은 다음과 같은 형식의 HTTP GET 요청입니다.

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

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

https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEY

또는 curl 명령어에서 다음과 같이 합니다.

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

장소 세부정보 (신규) 응답

장소 세부정보 (신규)는 JSON 객체를 응답으로 반환합니다. 응답에서 각 항목의 의미는 다음과 같습니다.

  • 응답은 Place 객체로 표시됩니다. Place 객체에는 장소에 대한 자세한 정보가 포함되어 있습니다.
  • 요청에 전달된 FieldMaskPlace 객체에서 반환되는 필드의 목록을 지정합니다.

전체 JSON 객체의 형식은 다음과 같습니다.

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "displayName": {
    "text": "Trinidad"
  }
  ...
}

필수 매개변수

  • FieldMask

    응답 필드 마스크를 만들어 응답에서 반환할 필드의 목록을 지정합니다. URL 매개변수 $fields 또는 fields를 사용하거나 HTTP 헤더 X-Goog-FieldMask를 사용하여 응답 필드 마스크를 메서드에 전달합니다. 응답에서 반환되는 필드의 기본 목록은 없습니다. 필드 마스크를 생략하면 메서드가 오류를 반환합니다.

    필드 마스크를 사용하면 불필요한 데이터의 요청을 방지하여 불필요한 처리에 드는 시간과 요금을 막을 수 있습니다.

    반환할 장소 데이터 유형의 쉼표로 구분된 목록을 지정합니다. 예를 들어, 장소의 표시 이름과 주소를 가져오려면 다음을 실행합니다.

    X-Goog-FieldMask: displayName,formattedAddress

    *를 사용하여 모든 필드를 가져옵니다.

    X-Goog-FieldMask: *

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

    • 다음 필드는 장소 세부정보 Essentials IDs Only SKU를 트리거합니다.

      attributions
      id
      moved_place
      moved_place_id
      name*
      photos

      * name 필드에는 장소 리소스 이름places/PLACE_ID 형식으로 포함됩니다. 장소의 텍스트 이름을 가져오려면 Pro SKU에서 displayName 필드를 요청하세요.

    • 다음 필드는 장소 세부정보 Essentials SKU를 트리거합니다.

      addressComponents
      addressDescriptor*
      adrFormatAddress
      formattedAddress
      location
      plusCode
      postalAddress
      shortFormattedAddress
      types
      viewport

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

    • 다음 필드는 장소 세부정보 Pro SKU를 트리거합니다.

      accessibilityOptions
      businessStatus
      containingPlaces
      displayName
      googleMapsLinks
      googleMapsUri
      iconBackgroundColor
      iconMaskBaseUri
      openingDate
      primaryType
      primaryTypeDisplayName
      pureServiceAreaBusiness
      subDestinations
      timeZone
      utcOffsetMinutes

    • 다음 필드는 장소 세부정보 Enterprise SKU를 트리거합니다.

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

    • 다음 필드는 장소 세부정보 Enterprise + Atmosphere SKU를 트리거합니다.

      allowsDogs
      curbsidePickup
      delivery
      dineIn
      editorialSummary
      evChargeAmenitySummary
      evChargeOptions
      fuelOptions
      generativeSummary
      goodForChildren
      goodForGroups
      goodForWatchingSports
      liveMusic
      menuForChildren
      neighborhoodSummary
      parkingOptions
      paymentOptions
      outdoorSeating
      reservable
      restroom
      reviews
      reviewSummary
      routingSummaries*
      servesBeer
      servesBreakfast
      servesBrunch
      servesCocktails
      servesCoffee
      servesDessert
      servesDinner
      servesLunch
      servesVegetarianFood
      servesWine
      takeout

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

  • placeId

    장소를 고유하게 식별하는 텍스트 식별자로, 텍스트 검색 (신규) 또는 주변 지역 검색 (신규)에서 반환됩니다. 장소 ID에 대한 자세한 내용은 장소 ID 개요를 참고하세요.

    문자열 places/PLACE_ID는 장소 리소스 이름이라고도 합니다. Place Details (New), 주변 지역 검색 (신규), 텍스트 검색 (신규) 요청의 응답에서 이 문자열은 응답의 name 필드에 포함됩니다. 독립형 장소 ID는 응답의 id 필드에 포함됩니다.

선택적 매개변수

  • languageCode

    결과를 반환할 언어입니다.

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

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

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

    대부분의 CLDR 코드는 ISO 3166-1 코드와 동일하지만 일부 주목할 만한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk'(.co.uk)이지만 ISO 3166-1 코드는 'gb'(엄밀히 말하면 '영국'의 항목)입니다. 이 매개변수는 관련 법률에 따라 결과에 영향을 미칠 수 있습니다.

  • sessionToken

    세션 토큰은 자동 완성 (신규) 호출을 "세션"으로 추적하는 사용자 생성 문자열입니다. 자동 완성 (신규)은 세션 토큰을 사용하여 사용자 자동 완성 검색의 쿼리 및 장소 선택 단계를 결제 목적의 개별 세션으로 그룹화합니다. 세션 토큰은 자동 완성 (신규) 호출 다음에 오는 장소 세부정보 (신규) 호출에 전달됩니다. 자세한 내용은 세션 토큰을 참고하세요.

장소 세부정보 (신규) 예

다음 예에서는 placeId로 장소의 세부정보를 요청합니다.

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

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

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

필드 마스크에 데이터 유형을 추가하여 추가 정보를 반환합니다. 예를 들어 응답에 주소와 Plus Code를 포함하려면 formattedAddress,plusCode를 추가합니다.

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,formattedAddress,plusCode" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

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

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "plusCode": {
    "globalCode": "849VCWC7+RW",
    "compoundCode": "CWC7+RW Mountain View, CA, USA"
  },
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

주소 설명자 가져오기

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

다음 예는 산호세 쇼핑몰의 백화점에 대한 장소 세부정보 (New) 요청을 보여줍니다. 이 예에서는 필드 마스크에 addressDescriptors 을 포함합니다.

  curl -X GET https://places.googleapis.com/v1/places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4 \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  -H "X-Goog-FieldMask: name,displayName,addressDescriptor"

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

  {
    "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
    "displayName": {
      "text": "Macy's",
      "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": 220.29175
        },
        {
          "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": 329.45178
        },
        {
          "name": "places/ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "placeId": "ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "displayName": {
            "text": "Monroe Parking Garage",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "parking",
            "point_of_interest"
          ],
          "straightLineDistanceMeters": 227.05153
        },
        {
          "name": "places/ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "placeId": "ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "displayName": {
            "text": "Studios Inn by Daiwa Living California Inc.",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "lodging",
            "point_of_interest",
            "real_estate_agency"
          ],
          "straightLineDistanceMeters": 299.9955
        },
        {
          "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "displayName": {
            "text": "Din Tai Fung",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "food",
            "point_of_interest",
            "restaurant"
          ],
          "straightLineDistanceMeters": 157.70943
        }
      ],
      "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"
        }
      ]
    }
  }

이전된 장소의 장소 세부정보 가져오기

앱에서 참조된 장소가 이전된 경우 movedPlacemovedPlaceId 필드를 사용하여 새 장소의 세부정보를 가져올 수 있습니다.

영구적으로 폐업한 장소의 경우 장소 세부정보 (New)는 CLOSED_PERMANENTLY 필드에 businessStatus를 반환하고 응답 본문에서 movedPlacemovedPlaceId 필드를 생략합니다.

새 위치로 이전한 장소의 경우 장소 세부정보 (신규)는 CLOSED_PERMANENTLY 필드에 businessStatus를 반환하고 응답 본문의 movedPlacemovedPlaceId 필드에 새 위치를 반환합니다.

이전하지 않은 장소의 경우 장소 세부정보 (신규)는 응답 본문에서 movedPlace 또는 movedPlaceId를 반환하지 않습니다.

다음 예에서는 캐나다 퀘벡의 Marche IGA St-Canut에 관한 장소 정보를 요청합니다.

curl -X  GET -H 'Content-Type: application/json' \
-H 'x-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: id,displayName,businessStatus,movedPlace,movedPlaceId' \
https://places.googleapis.com/v1/places/ChIJUfQdGInVzkwRzAjmjzWB7CQ

요청은 다음 응답을 반환합니다.

{
  "id": "ChIJUfQdGInVzkwRzAjmjzWB7CQ",
  "businessStatus": "CLOSED_PERMANENTLY",
  "displayName": {
    "text": "Marche IGA St-Canut",
    "languageCode": "en"
  },
  "movedPlace": "places/ChIJ36QT7n8qz0wRDqVZ_UBlUlQ",
  "movedPlaceId": "ChIJ36QT7n8qz0wRDqVZ_UBlUlQ"
}

새 장소에 관한 세부정보를 요청하려면 새 장소 세부정보 (신규) 요청의 movedPlace 필드에서 장소 리소스 이름을 사용하세요.

여러 번 이전한 장소의 경우 현재 위치에 관한 세부정보를 가져오려면 여러 개의 연결된 장소 세부정보 (New) 요청이 필요할 수 있습니다. 장소 결과의 movedPlacemovedPlaceId 필드는 마지막 알려진 위치가 아닌 다음 위치만 가리킵니다. Place Details (New) 요청 이 응답 본문에서 movedPlacemovedPlaceId 필드를 생략하면 장소는 현재 위치에 있습니다.

향후 개업하는 비즈니스 찾기

향후 개업할 것으로 예상되는 비즈니스에 관한 세부정보를 요청할 수 있습니다. 예상 개업일이 최소한 월을 포함하고 90일 이내인 경우 주변 지역 검색 (신규)은 openingDate 필드를 채웁니다.

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

curl -X GET \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,businessStatus,openingDate" \
"https://places.googleapis.com/v1/places/ChIJp1-VoKWJplQRMz8g-7Wa3Do"

응답에는 장소의 비즈니스 상태와 예상 개업일이 포함됩니다.

{
  "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
  "businessStatus": "FUTURE_OPENING",
  "openingDate": {
    "year": 2026,
    "month": 4,
    "day": 15
  }
}

대중교통 정류장 정보 가져오기

장소 세부정보 (신규)를 사용하여 대중교통 역/정류장에 관한 정보를 가져올 수 있습니다. 응답 본문에는 정류장 이름, 제휴 대중교통 기관, 정류장을 운행하는 대중교통 노선 등 정류장에 관한 정보가 포함됩니다. 또한 응답에는 대중교통 정류장 정보를 표시하는 데 사용할 수 있는 차량 아이콘과 색상이 포함됩니다.

다음 예는 그랜드 센트럴 터미널의 대중교통 정류장 정보 요청을 보여줍니다.

curl -X GET \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,transitStation" \
"https://places.googleapis.com/v1/places/ChIJLVaKiQFZwokRgcybX3K6Pzg"

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

  {
  "id": "ChIJLVaKiQFZwokRgcybX3K6Pzg",
  "displayName": {
    "text": "Grand Central",
    "languageCode": "en"
  },
  "transitStation": {
    "displayName": {
      "text": "Grand Central",
      "languageCode": "en"
    },
    "agencies": [
      {
        "displayName": {
          "text": "MTA New York City Transit",
          "languageCode": "en"
        },
        "url": "http://www.mta.info/",
        "lines": [
          {
            "id": "ChIJ420yFwBZwokR903kVZLSsFc",
            "vehicleType": "SUBWAY",
            "displayName": {
              "text": "42 St Shuttle",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "S",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#808183",
            "url": "https://www.mta.info/schedules/subway/42-st-shuttle",
            "icon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/S.svg",
              "nameIncluded": true
            },
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg"
            }
          },
          {
            "id": "ChIJDdd_uEdfwokRHbLvWrdBdDM",
            "vehicleType": "SUBWAY",
            "displayName": {
              "text": "5 Train (Lexington Av Express)",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "5 Line",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#00933C",
            "url": "https://www.mta.info/schedules/subway/5-train",
            "icon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/5.svg",
              "nameIncluded": true
            },
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg"
            }
          }
          ...
        ]
      },
      {
        "displayName": {
          "text": "MTA",
          "languageCode": "en"
        },
        "url": "https://new.mta.info/",
        "lines": [
          {
            "id": "ChIJcwVpzKpZwokR24EBeh8arww",
            "vehicleType": "BUS",
            "displayName": {
              "text": "United Nations - W 42 St Pier",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "M42",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#1D59B3",
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg"
            }
          }
        ]
      },
      {
        "displayName": {
          "text": "Long Island Rail Road",
          "languageCode": "en"
        },
        "url": "http://www.mta.info/lirr",
        "lines": [
          {
            "id": "ChIJv9m8uWM56IkRUcVBQ6Q_In0",
            "vehicleType": "HEAVY_RAIL",
            "displayName": {
              "text": "Ronkonkoma Branch",
              "languageCode": "en"
            },
            "shortDisplayName": {
              "text": "LIRR",
              "languageCode": "en"
            },
            "textColor": "#FFFFFF",
            "backgroundColor": "#A626AA",
            "vehicleIcon": {
              "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg"
            }
          }
          ...
        ]
      }
    ],
    "stops": [
      {
        "id": "ChIJRcemlf1YwokRhFqqw5jKBFM",
        "stopCode": {
          "text": "GCT"
        },
        "location": {
          "latitude": 40.755161,
          "longitude": -73.975456
        },
        "wheelchairAccessibleEntrance": true
      },
      {
        "id": "ChIJ57l2zANZwokRD1pyhuwpfKY",
        "signageText": {
          "text": "34 St-Hudson Yards & Main St-Flushing, Queens, 7",
          "languageCode": "en"
        },
        "location": {
          "latitude": 40.750983,
          "longitude": -73.9750686
        },
        "wheelchairAccessibleEntrance": true
      },
      {
        "id": "ChIJoVXJgQFZwokR1yzq_WVuEuc",
        "displayName": {
          "text": "E 42 St/Park Av",
          "languageCode": "en"
        },
        "location": {
          "latitude": 40.7518199,
          "longitude": -73.9771918
        },
        "wheelchairAccessibleEntrance": true
      }
      ...
    ]
  }
}

사용해 보기

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

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

  2. 필요에 따라 요청 매개변수를 수정합니다.

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

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