รายละเอียดสถานที่ (ใหม่)

เลือกแพลตฟอร์ม: Android iOS JavaScript เว็บเซอร์วิส
นักพัฒนาซอฟต์แวร์ในเขตเศรษฐกิจยุโรป (EEA)

บทนำ

เมื่อมีรหัสสถานที่แล้ว คุณจะ ขอรายละเอียดเพิ่มเติมเกี่ยวกับสถานประกอบการหรือ จุดที่น่าสนใจที่เฉพาะเจาะจงได้โดยการเริ่มคำขอ รายละเอียดสถานที่ (ใหม่) คำขอรายละเอียดสถานที่ (ใหม่) จะแสดงข้อมูลที่ครอบคลุมมากขึ้นเกี่ยวกับสถานที่ที่ระบุ เช่น ที่อยู่แบบเต็ม หมายเลขโทรศัพท์ คะแนนและรีวิวของผู้ใช้

คุณรับรหัสสถานที่ได้หลายวิธี โดยคุณสามารถใช้สิ่งต่อไปนี้ได้

โปรแกรมสำรวจ 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 มีข้อมูลโดยละเอียดเกี่ยวกับ สถานที่
  • FieldMask ที่ส่งในคำขอจะระบุรายการฟิลด์ ที่แสดงผลในออบเจ็กต์ Place

ออบเจ็กต์ 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: *

    ระบุช่องต่อไปนี้อย่างน้อย 1 ช่อง

    • ฟิลด์ต่อไปนี้จะทริกเกอร์ SKU ที่มีเฉพาะรหัสข้อมูลสำคัญของรายละเอียดสถานที่

      attributions
      id
      moved_place
      moved_place_id
      name*
      photos

      * ฟิลด์ name มีชื่อทรัพยากรของสถานที่ ในรูปแบบ places/PLACE_ID หากต้องการรับชื่อข้อความของสถานที่ ให้ขอฟิลด์ displayName ใน Pro SKU

    • ฟิลด์ต่อไปนี้จะทริกเกอร์ Place Details Essentials SKU

      addressComponents
      addressDescriptor*
      adrFormatAddress
      formattedAddress
      location
      plusCode
      postalAddress
      shortFormattedAddress
      types
      viewport

      * คำอธิบายที่อยู่พร้อมให้บริการแก่ลูกค้าในอินเดียโดยทั่วไป และเป็นเวอร์ชันทดลองในประเทศอื่นๆ

    • ฟิลด์ต่อไปนี้จะทริกเกอร์ Place Details Pro SKU

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

    • ฟิลด์ต่อไปนี้จะทริกเกอร์ SKU รายละเอียดสถานที่สำหรับองค์กร

      currentOpeningHours
      currentSecondaryOpeningHours
      internationalPhoneNumber
      nationalPhoneNumber
      priceLevel
      priceRange
      rating
      regularOpeningHours
      regularSecondaryOpeningHours
      userRatingCount
      websiteUri

    • ฟิลด์ต่อไปนี้จะทริกเกอร์ SKU รายละเอียดสถานที่ Enterprise + Atmosphere

      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

    ตัวระบุข้อความที่ระบุค่าเฉพาะของสถานที่ ซึ่งส่งคืนจาก การค้นหาข้อความ (ใหม่) หรือ การค้นหาใกล้เคียง (ใหม่) ดูข้อมูลเพิ่มเติมเกี่ยวกับรหัสสถานที่ได้ที่ภาพรวมรหัสสถานที่

    สตริง places/PLACE_ID เรียกอีกอย่างว่าชื่อทรัพยากรของสถานที่ ในการตอบกลับจากคำขอ Place Details (ใหม่), Nearby Search (ใหม่) และ Text Search (ใหม่) สตริงนี้จะอยู่ในฟิลด์ name ของการตอบกลับ รหัสสถานที่แบบสแตนด์อโลน อยู่ในฟิลด์ id ของการตอบกลับ

พารามิเตอร์ที่ไม่บังคับ

  • languageCode

    ภาษาที่จะแสดงผลลัพธ์

    • ดู รายการภาษาที่รองรับ Google มักจะอัปเดต ภาษาที่รองรับอยู่เสมอ ดังนั้นรายการนี้จึงอาจไม่ครอบคลุมทั้งหมด
    • หากไม่ได้ระบุ languageCode API จะใช้ en เป็นค่าเริ่มต้น หาก คุณระบุรหัสภาษาที่ไม่ถูกต้อง API จะแสดงข้อผิดพลาด INVALID_ARGUMENT
    • API จะพยายามอย่างเต็มที่เพื่อให้ที่อยู่ที่อ่านง่ายสำหรับทั้งผู้ใช้และคนในพื้นที่ เพื่อให้บรรลุเป้าหมายดังกล่าว ระบบจะแสดงที่อยู่ในภาษาท้องถิ่น โดยแปลงเป็นสคริปต์ที่ผู้ใช้อ่านได้หากจำเป็น ตามภาษาที่ต้องการ ส่วนที่อยู่อื่นๆ จะแสดงในภาษาที่ต้องการ คอมโพเนนต์ของที่อยู่ ทั้งหมดจะแสดงในภาษาเดียวกัน ซึ่งเลือกจากคอมโพเนนต์แรก
    • หากชื่อไม่มีในภาษาที่ต้องการ API จะใช้ชื่อที่ใกล้เคียงที่สุด
    • ภาษาที่ต้องการมีผลเล็กน้อยต่อชุดผลลัพธ์ที่ API เลือกที่จะแสดงผล และลำดับที่แสดงผล Geocoder จะตีความตัวย่อแตกต่างกันไปตามภาษา เช่น ตัวย่อสำหรับประเภทถนน หรือคำพ้องความหมายที่อาจ ใช้ได้ในภาษาหนึ่งแต่ใช้ไม่ได้ในอีกภาษาหนึ่ง
  • regionCode

    รหัสภูมิภาคที่ใช้จัดรูปแบบการตอบกลับ โดยระบุเป็นค่า รหัส CLDR 2 หลัก ไม่มีค่าเริ่มต้น

    หากชื่อประเทศของฟิลด์ 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"
  }
}

เพิ่มประเภทข้อมูลลงในมาสก์ฟิลด์เพื่อแสดงข้อมูลเพิ่มเติม เช่น เพิ่ม formattedAddress,plusCode เพื่อรวมที่อยู่และ Plus Code ในการตอบกลับ

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

รับตัวอธิบายที่อยู่

ข้อบ่งชี้ที่อยู่จะให้ข้อมูลเชิงสัมพันธ์เกี่ยวกับตำแหน่งของสถานที่ ซึ่งรวมถึงสถานที่สำคัญและพื้นที่โดยรอบ

ตัวอย่างต่อไปนี้แสดงคำขอรายละเอียดสถานที่ (ใหม่) สำหรับห้างสรรพสินค้า ในห้างสรรพสินค้าในซานโฮเซ ในตัวอย่างนี้ คุณจะใส่ 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"
        }
      ]
    }
  }

ดูรายละเอียดสถานที่สำหรับสถานที่ที่ย้ายแล้ว

หากสถานที่ที่อ้างอิงในแอปของคุณย้ายที่ตั้ง คุณสามารถใช้ฟิลด์ movedPlace และ movedPlaceId เพื่อดูรายละเอียดของสถานที่ใหม่ได้

สำหรับสถานที่ที่ปิดถาวร รายละเอียดสถานที่ (ใหม่) จะแสดง CLOSED_PERMANENTLY ในฟิลด์ businessStatus และละเว้นฟิลด์ movedPlace และ movedPlaceId ในเนื้อหาการตอบกลับ

สำหรับสถานที่ที่ย้ายไปยังตำแหน่งใหม่ รายละเอียดสถานที่ (ใหม่) จะแสดง CLOSED_PERMANENTLY ในฟิลด์ businessStatus และแสดงตำแหน่งใหม่ในฟิลด์ movedPlace และ movedPlaceId ของเนื้อหาการตอบกลับ

สำหรับสถานที่ที่ไม่ได้ย้าย รายละเอียดสถานที่ (ใหม่) จะไม่แสดง 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 ในคำขอรายละเอียดสถานที่ (ใหม่) ใหม่

สำหรับสถานที่ที่ย้ายหลายครั้ง การดูรายละเอียดเกี่ยวกับตำแหน่งปัจจุบัน อาจต้องใช้คำขอรายละเอียดสถานที่ (ใหม่) ที่เชื่อมโยงกันหลายรายการ ฟิลด์ movedPlace และ movedPlaceId ของผลการค้นหาสถานที่จะชี้ไปยังตำแหน่งถัดไปเท่านั้น ไม่ใช่ตำแหน่งสุดท้าย ที่ทราบ สถานที่จะอยู่ในตำแหน่งปัจจุบันหากคำขอรายละเอียดสถานที่ (ใหม่) ละเว้นฟิลด์ movedPlace และ movedPlaceId ในเนื้อหาการตอบกลับ

ค้นหาธุรกิจที่จะเปิดในอนาคต

คุณขอรายละเอียดเกี่ยวกับธุรกิจที่คาดว่าจะเปิดในอนาคตได้ การค้นหาใกล้เคียง (ใหม่) จะป้อนข้อมูลในช่อง openingDate หากวันที่เปิดที่คาดการณ์มีเดือนเป็นอย่างน้อยและอยู่ห่างออกไปไม่เกิน 90 วัน

ตัวอย่างต่อไปนี้แสดงคำขอการค้นหาใกล้เคียง (ใหม่) สำหรับธุรกิจที่จะเปิดในอนาคตในนิวมีโดวส์ รัฐไอดาโฮ

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
  }
}

ลองใช้งาน

โปรแกรมสำรวจ API ช่วยให้คุณส่งคำขอตัวอย่างได้ เพื่อให้คุ้นเคยกับ API และตัวเลือก API

  1. เลือกไอคอน API api ทางด้านขวาของหน้า

  2. แก้ไขพารามิเตอร์คำขอ (ไม่บังคับ)

  3. เลือกปุ่มดำเนินการ ในกล่องโต้ตอบ ให้เลือกบัญชี ที่ต้องการใช้เพื่อส่งคำขอ

  4. ในแผงโปรแกรมสำรวจ API ให้เลือกไอคอนเต็มหน้าจอ fullscreen เพื่อขยายหน้าต่างโปรแกรมสำรวจ API