ห้องสมุดของ Places

เลือกแพลตฟอร์ม: Android iOS JavaScript บริการเว็บ

หมายเหตุ: บังคับใช้ข้อจํากัดของคีย์ API แล้ว

เรากําลังบังคับใช้ข้อจํากัดคีย์ API สําหรับไลบรารี Places, Maps JavaScript API ซึ่งจะมีผลตั้งแต่วันที่ 16 กันยายน 2019 หากใช้ข้อจํากัด API กับคีย์ API ที่ใช้กับไลบรารีสถานที่, Maps JavaScript API และไม่ได้เลือกทั้ง Places API และ Maps JavaScript API ในรายการข้อจํากัด API คุณจะเริ่มพบข้อผิดพลาด ดูการเริ่มต้นใช้งานไลบรารีสถานที่สําหรับการตั้งค่าโปรเจ็กต์ที่จําเป็น

หมายเหตุ: ไลบรารีฝั่งเซิร์ฟเวอร์

หน้านี้อธิบายบริการฝั่งไคลเอ็นต์ที่ใช้ได้กับ Maps JavaScript API หากต้องการทํางานกับบริการเว็บ Google Maps บนเซิร์ฟเวอร์ โปรดดูไคลเอ็นต์ Node.js สําหรับบริการ Google Maps นอกจากนี้ หน้าเว็บที่ลิงก์ดังกล่าวยังแสดงไคลเอ็นต์ Java, ไคลเอ็นต์ Python และไคลเอ็นต์ Go สําหรับบริการ Google Maps ด้วย

ภาพรวม

ฟังก์ชันในไลบรารีสถานที่, Maps JavaScript API ช่วยให้แอปพลิเคชันค้นหาสถานที่ (ซึ่งระบุไว้ใน API นี้เป็นสถานประกอบการ สถานที่ตั้งทางภูมิศาสตร์ หรือจุดสนใจสําคัญ) ซึ่งอยู่ในพื้นที่ที่กําหนด เช่น ขอบเขตแผนที่หรือรอบๆ ตําแหน่งคงที่

Places API มีฟีเจอร์เติมข้อความอัตโนมัติที่คุณสามารถใช้เพื่อให้แอปพลิเคชันค้นหาข้อมูลประเภทต่อจากช่องค้นหาของ Google Maps เมื่อผู้ใช้เริ่มพิมพ์ที่อยู่ การเติมข้อความอัตโนมัติจะเติมข้อความที่เหลือ ดูข้อมูลเพิ่มเติมได้ในเอกสารประกอบเกี่ยวกับการเติมข้อความอัตโนมัติ

การเริ่มต้นใช้งาน

หากคุณไม่คุ้นเคยกับ Maps JavaScript API หรือ JavaScript เราขอแนะนําให้ตรวจสอบ JavaScript และรับคีย์ API ก่อนเริ่มต้น

เปิดใช้ API

ก่อนที่จะใช้ไลบรารี Places ใน Maps JavaScript API ก่อนอื่นให้ตรวจสอบว่า Places API เปิดใช้งานอยู่ใน Google Cloud Console ในโปรเจ็กต์เดียวกับที่คุณตั้งค่าไว้สําหรับ Maps JavaScript API

วิธีดูรายการ API ที่เปิดใช้

1. ไปที่ Google Cloud Console
2. คลิกปุ่มเลือกโปรเจ็กต์ แล้วเลือกโปรเจ็กต์เดียวกับที่ตั้งค่าไว้สําหรับ Maps JavaScript API แล้วคลิกเปิด
3. ค้นหา Places API จากรายการ API ในหน้าแดชบอร์ด
4. หากคุณเห็น Places API ในรายการ แสดงว่า API นั้นเปิดใช้อยู่แล้ว หาก ไม่ แสดงอยู่ใน API ให้เปิดใช้
   1. ที่ด้านบนของหน้า ให้เลือกเปิดใช้ API และบริการเพื่อแสดงแท็บไลบรารี หรือเลือกคลังจากเมนูด้านซ้าย
   2. ค้นหา Places API จากนั้นเลือกจากรายการผลลัพธ์
   3. เลือกเปิดใช้ เมื่อเสร็จสิ้นกระบวนการแล้ว Places API จะปรากฏในรายการ API บนหน้าแดชบอร์ด

กําลังโหลดไลบรารี

บริการ Places เป็นไลบรารีที่ครอบคลุมในตัวซึ่งแยกจากโค้ดหลักของ JavaScript JavaScript API หากต้องการใช้ฟังก์ชันที่มีอยู่ในไลบรารีนี้ ก่อนอื่นคุณต้องโหลดโดยใช้พารามิเตอร์ libraries ใน URL รองเท้าบู๊ตของ Maps API

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>

ดูภาพรวมไลบรารีสําหรับข้อมูลเพิ่มเติม

เพิ่ม Places API ลงในรายการข้อจํากัด API ของคีย์ API

การใช้ข้อจํากัด API กับคีย์ของคุณจะจํากัดการใช้คีย์ API สําหรับ API หรือ SDK อย่างน้อย 1 รายการ คําขอที่ส่งไปยัง API หรือ SDK ที่เชื่อมโยงกับคีย์ API จะได้รับการประมวลผล คําขอไปยัง API หรือ SDK ที่ไม่ได้เชื่อมโยงกับคีย์ API จะล้มเหลว วิธีจํากัดคีย์ API เพื่อใช้กับไลบรารี Places ของ Maps JavaScript API

1. ไปที่ Google Cloud Console
2. คลิกเมนูแบบเลื่อนลงของโปรเจ็กต์ แล้วเลือกโปรเจ็กต์ที่มีคีย์ API ที่ต้องการรักษาความปลอดภัย
3. คลิกปุ่มเมนู แล้วเลือก Google Maps Platform > ข้อมูลเข้าสู่ระบบ
4. คลิกชื่อคีย์ API ที่ต้องการรักษาความปลอดภัยในหน้าข้อมูลเข้าสู่ระบบ
5. ในหน้าจํากัดและเปลี่ยนชื่อคีย์ API ให้ตั้งค่าข้อจํากัด
   
   • ข้อจำกัด API
   • เลือกจํากัดคีย์
   • คลิกเลือก API แล้วเลือกทั้ง Maps JavaScript API และ Places API
     (หาก API อย่างใดอย่างหนึ่งไม่อยู่ในรายการ คุณต้องเปิดใช้ API)
6. คลิกบันทึก

ขีดจํากัดและนโยบายการใช้งาน

โควต้า

ไลบรารี Places ซึ่งเป็น JavaScript API จะแชร์โควต้าการใช้งานกับ Places API ตามที่อธิบายไว้ในเอกสารประกอบของขีดจํากัดการใช้งานสําหรับ Places API

นโยบาย

การใช้ไลบรารีสถานที่คือ Maps JavaScript API ต้องเป็นไปตามนโยบายที่อธิบายเกี่ยวกับ Places API

การค้นหาสถานที่

ด้วยบริการ Places คุณจะสามารถทําการค้นหาประเภทต่อไปนี้

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

ข้อมูลที่แสดงผลอาจรวมถึงสถานประกอบการ เช่น ร้านอาหาร ร้านค้า และสํานักงาน รวมถึงผลการค้นหา "ไวลด์การ์ด" ซึ่งระบุที่อยู่ พื้นที่ทางการเมือง เช่น เมืองและจุดสนใจอื่นๆ

ค้นหาคําขอสถานที่

คําขอ "ค้นหาสถานที่" ช่วยให้คุณค้นหาสถานที่ได้โดยการค้นหาข้อความหรือหมายเลขโทรศัพท์ คําขอค้นหาสถานที่มี 2 ประเภท ได้แก่

• ค้นหาสถานที่จากคําค้นหา
• ค้นหาสถานที่จากหมายเลขโทรศัพท์

ค้นหาสถานที่จากคําค้นหา

การค้นหาสถานที่จากข้อความค้นหาป้อนอินพุตข้อความและแสดงสถานที่ ข้อมูลที่ป้อนอาจเป็นข้อมูลสถานที่ประเภทใดก็ได้ เช่น ชื่อธุรกิจหรือที่อยู่ หากต้องการส่งคําขอ ค้นหาสถานที่จากคําขอ ให้เรียกใช้เมธอดของ PlacesServicefindPlaceFromQuery() ซึ่งจะใช้พารามิเตอร์ต่อไปนี้

• query (ต้องระบุ) สตริงข้อความที่จะค้นหา เช่น "ร้านอาหาร" หรือ "123 ถนนสีลม" ต้องเป็นชื่อสถานที่ ที่อยู่ หรือหมวดหมู่สถานที่ อินพุตประเภทอื่นๆ อาจทําให้เกิดข้อผิดพลาดได้ และไม่รับประกันว่าจะแสดงผลการค้นหาที่ถูกต้อง Places API จะแสดงผลการจับคู่ผู้สมัครตามสตริงนี้และเรียงลําดับผลการค้นหาตามความเกี่ยวข้องที่เห็น
• fields (ต้องระบุ) ช่องอย่างน้อย 1 ช่องซึ่งระบุประเภทของข้อมูลสถานที่ที่จะแสดง
• locationBias (ไม่บังคับ) พิกัดที่กําหนดพื้นที่เพื่อค้นหา อาจมีสถานะอย่างใดอย่างหนึ่งต่อไปนี้
  • ชุดของพิกัดละติจูดและลองจิจูดที่แสดงเป็น LatLngLiteral หรือออบเจ็กต์ LaLLng
  • ขอบเขตสี่เหลี่ยมผืนผ้า (คู่ละติน/คู่ 2 คู่ หรือออบเจ็กต์ LatLngBounds)
  • รัศมี (หน่วยเป็นเมตร) ศูนย์กลางของละติจูด/ปลาย

และคุณต้องส่งผ่านเมธอดเรียกกลับไปยัง findPlaceFromQuery() เพื่อจัดการออบเจ็กต์ผลลัพธ์และการตอบกลับของ google.maps.places.PlacesServiceStatus

ตัวอย่างต่อไปนี้แสดงการเรียกใช้ findPlaceFromQuery() ค้นหา "พิพิธภัณฑ์งานศิลปะร่วมสมัยออสเตรเลีย" รวมถึงช่อง name และ geometry

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

  map = new google.maps.Map(
      document.getElementById('map'), {center: sydney, zoom: 15});

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

  var service = new google.maps.places.PlacesService(map);

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}

ดูตัวอย่าง

ค้นหาสถานที่จากหมายเลขโทรศัพท์

"ค้นหาสถานที่จากหมายเลขโทรศัพท์" จะใช้หมายเลขโทรศัพท์และส่งคืนสถานที่ หากต้องการส่งคําขอค้นหาสถานที่จากหมายเลขโทรศัพท์ ให้เรียกเมธอด findPlaceFromPhoneNumber() ของ PlacesService ซึ่งใช้พารามิเตอร์ต่อไปนี้

• phoneNumber (ต้องระบุ) หมายเลขโทรศัพท์ในรูปแบบ E.164
• fields (ต้องระบุ) ช่องอย่างน้อย 1 ช่องซึ่งระบุประเภทของข้อมูลสถานที่ที่จะแสดง
• locationBias (ไม่บังคับ) พิกัดที่กําหนดพื้นที่เพื่อค้นหา ซึ่งอาจเป็นอย่างใดอย่างหนึ่งต่อไปนี้
  • ชุดของพิกัดละติจูดและลองจิจูดที่แสดงเป็น LatLngLiteral หรือออบเจ็กต์ LaLLng
  • ขอบเขตสี่เหลี่ยมผืนผ้า (จุดลาติน/สี่จุดหรือออบเจ็กต์ LaLngBounds)
  • รัศมี (หน่วยเป็นเมตร) ศูนย์กลางของละติจูด/ปลาย

และคุณต้องส่งผ่านเมธอดเรียกกลับไปยัง findPlaceFromPhoneNumber() เพื่อจัดการออบเจ็กต์ผลลัพธ์และการตอบกลับของ google.maps.places.PlacesServiceStatus

ช่อง (ดูวิธีการเกี่ยวกับสถานที่)

เราจะเลิกใช้งานช่อง Places opening_hours.open_now และ utc_offset ใน Places SDK สําหรับ iOS ตั้งแต่วันที่ 20 พฤศจิกายน 2019 เป็นต้นไป และจะเลิกใช้งานวันที่ 20 กุมภาพันธ์ 2021 ดูข้อมูลเพิ่มเติม

ใช้พารามิเตอร์ fields เพื่อระบุอาร์เรย์ของประเภทข้อมูลสถานที่ที่จะแสดง เช่น fields: ['formatted_address', 'opening_hours', 'geometry'] ใช้จุดเมื่อระบุค่าผสม เช่น opening_hours.weekday_text

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

ข้อควรระวัง: คําขอสถานที่และคําขอรายละเอียดสถานที่ไม่แสดงช่องเดียวกัน คําขอการค้นหาสถานที่จะแสดงชุดย่อยของช่องที่แสดงผลโดยคําขอรายละเอียดสถานที่ หากช่องค้นหาที่ต้องการไม่แสดงช่องที่คุณต้องการ คุณสามารถใช้การค้นหาสถานที่เพื่อรับ place_id แล้วใช้รหัสสถานที่ในการส่งคําขอรายละเอียดสถานที่

พื้นฐาน

หมวดหมู่พื้นฐานจะมีช่องต่อไปนี้
business_status, formatted_address, geometry, icon,icon_mask_base_uri, icon_background_color, name, permanently_closed (เลิกใช้งาน), photos, place_id, plus_code, types

ข้อมูลติดต่อ

หมวดหมู่รายชื่อติดต่อจะมีช่องต่อไปนี้ opening_hours
(เลิกใช้งาน ในไลบรารีสถานที่ของ Maps JavaScript API ใช้คําขอรายละเอียดสถานที่เพื่อรับผลการค้นหา opening_hours)

บรรยากาศ

หมวดหมู่บรรยากาศประกอบด้วยช่องต่อไปนี้ price_level, rating, user_ratings_total

เมธอด findPlaceFromQuery() และ findPlaceFromPhoneNumber() จะใช้ช่องชุดเดียวกันและแสดงผลช่องเดียวกันในคําตอบที่เกี่ยวข้องได้

ตั้งค่าการให้น้ําหนักตําแหน่ง (ดูวิธีการเกี่ยวกับสถานที่)

ใช้พารามิเตอร์ locationBias เพื่อสร้างผลการค้นหาโปรดของ Place ในพื้นที่ใดพื้นที่หนึ่ง คุณตั้งค่า locationBias ได้ด้วยวิธีต่อไปนี้

การให้น้ําหนักผลลัพธ์ให้กับพื้นที่ที่ต้องการ:

locationBias: {lat: 37.402105, lng: -122.081974}

กําหนดพื้นที่สี่เหลี่ยมผืนผ้าที่จะค้นหา:

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

หรือจะใช้ LatLngBounds ก็ได้เช่นกัน

กําหนดรัศมีการค้นหา (หน่วยเป็นเมตร) โดยให้ศูนย์กลางอยู่ที่พื้นที่ใดพื้นที่หนึ่ง ดังนี้

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

คําขอการค้นหาสถานที่ใกล้เคียง

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

การค้นหาใกล้เคียงช่วยให้คุณค้นหาสถานที่ภายในพื้นที่ที่ระบุด้วยคีย์เวิร์ดหรือประเภทได้ การค้นหาบริเวณใกล้เคียงต้องมีตําแหน่งเสมอ ซึ่งสามารถระบุได้โดยใช้ 1 ใน 2 วิธีต่อไปนี้

• LatLngBounds
• พื้นที่วงกลมหมายถึงชุดค่าผสมของพร็อพเพอร์ตี้ location โดยระบุกึ่งกลางของวงกลมเป็นออบเจ็กต์ LatLng และรัศมีซึ่งวัดเป็นหน่วยเมตร

การค้นหา "สถานที่ใกล้เคียง" จะเริ่มต้นขึ้นโดยการเรียกเมธอด nearbySearch() ของ PlacesService ซึ่งจะแสดงอาร์เรย์ของออบเจ็กต์ PlaceResult โปรดทราบว่าเมธอด nearbySearch() จะแทนที่เมธอด search() ตั้งแต่เวอร์ชัน 3.9

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

วิธีนี้จะส่งคําขอด้วยช่องต่อไปนี้

• แบบใดแบบหนึ่งต่อไปนี้
  • bounds ซึ่งต้องเป็นออบเจ็กต์ google.maps.LatLngBounds ที่กําหนดพื้นที่การค้นหารูปสี่เหลี่ยมผืนผ้า หรือ
  • location และ radius ค่าแรกนําออบเจ็กต์ google.maps.LatLng มาคํานวณด้วยค่าที่สอง ส่วนจํานวนเต็มเป็นจํานวนเต็มของรัศมีของวงกลมในหน่วยเมตร รัศมีสูงสุดที่อนุญาตคือ 50,000 เมตร โปรดทราบว่าเมื่อตั้งค่า rankBy เป็น DISTANCE คุณต้องระบุ location แต่ไม่สามารถระบุ radius หรือ bounds
• keyword (ไม่บังคับ) - คําที่จะจับคู่กับช่องทั้งหมดที่ใช้ได้ ซึ่งรวมถึงแต่ไม่จํากัดเพียงชื่อ ประเภท และที่อยู่ ตลอดจนรีวิวของลูกค้าและเนื้อหาของบุคคลที่สามอื่นๆ
• minPriceLevel และ maxPriceLevel (ไม่บังคับ) — จํากัดผลการค้นหาเฉพาะสถานที่เหล่านั้นในช่วงที่ระบุ ค่าที่ใช้ได้จะอยู่ระหว่าง 0 (ประหยัดที่สุด) ถึง 4 (แพงที่สุด) รวม
• เลิกใช้ name แล้ว เทียบเท่ากับ keyword ค่าในช่องนี้จะรวมกับค่าในช่อง keyword และส่งเป็นส่วนหนึ่งของสตริงการค้นหาเดียวกัน
• openNow (ไม่บังคับ) — ค่าบูลีนที่ระบุว่าบริการ Places จะแสดงเฉพาะสถานที่ที่เปิดทําการในเวลาที่ส่งคําค้นหาเท่านั้น สถานที่ที่ไม่ระบุเวลาทําการในฐานข้อมูลของ Google Places จะไม่แสดง หากคุณใส่พารามิเตอร์นี้ในการค้นหา การตั้งค่า openNow เป็น false จะไม่มีผล
• rankBy (ไม่บังคับ) — ระบุลําดับการแสดงผลการค้นหา โดยค่าที่เป็นไปได้มีดังนี้
  • google.maps.places.RankBy.PROMINENCE (ค่าเริ่มต้น) ตัวเลือกนี้จะจัดเรียงผลการค้นหาตามความสําคัญ การจัดอันดับจะให้ความสําคัญกับตําแหน่งที่โดดเด่นภายในรัศมีที่กําหนดไว้เหนือสถานที่ใกล้เคียงที่ตรงกันแต่โดดเด่นน้อยกว่า ความโดดเด่นอาจได้รับผลกระทบจากการจัดอันดับของสถานที่ในดัชนีของ Google, ความนิยมทั่วโลก และปัจจัยอื่นๆ เมื่อ google.maps.places.RankBy.PROMINENCE ต้องระบุพารามิเตอร์ radius
  • google.maps.places.RankBy.DISTANCE ตัวเลือกนี้จะจัดเรียงผลลัพธ์ตามลําดับจากน้อยไปมากตามระยะทางจาก location ที่ระบุ (ต้องระบุ) โปรดทราบว่าคุณระบุ bounds และ/หรือ radius ที่กําหนดเองไม่ได้หากระบุ RankBy.DISTANCE เมื่อคุณระบุ RankBy.DISTANCE คุณต้องระบุ keyword, name หรือ type อย่างน้อย 1 รายการ
• type — จํากัดผลการค้นหาเฉพาะสถานที่ที่ตรงกับประเภทที่ระบุไว้ ระบบอาจระบุได้เพียงประเภทเดียว (หากมีการระบุมากกว่า 1 ประเภท) ระบบจะไม่สนใจทุกประเภทที่ติดตามรายการแรก) ดูรายการประเภทที่รองรับ

และคุณต้องส่งผ่านเมธอดเรียกกลับไปยัง nearbySearch() เพื่อจัดการออบเจ็กต์ผลลัพธ์และการตอบกลับของ google.maps.places.PlacesServiceStatus ด้วย

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    type: ['restaurant']
  };

  service = new google.maps.places.PlacesService(map);
  service.nearbySearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      createMarker(results[i]);
    }
  }
}

ดูตัวอย่าง

คําขอการค้นหาข้อความ

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

บริการ Google Search Text Search เป็นบริการบนเว็บที่แสดงข้อมูลเกี่ยวกับชุดสถานที่ที่อิงตามสตริง เช่น "ร้านพิซซ่าในกรุงเทพ" หรือ "ร้านรองเท้าใกล้สยาม" บริการจะตอบกลับด้วยรายการสถานที่ที่ตรงกับสตริงข้อความและการให้น้ําหนักตําแหน่งที่ตั้งค่าไว้ การตอบกลับการค้นหาจะรวมรายการสถานที่ คุณส่งคําขอรายละเอียดสถานที่เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับสถานที่ใดก็ได้ในการตอบกลับ

การค้นหาข้อความจะเริ่มต้นขึ้นด้วยการเรียกเมธอด textSearch() ของ PlacesService

service = new google.maps.places.PlacesService(map);
service.textSearch(request, callback);

วิธีนี้จะส่งคําขอด้วยช่องต่อไปนี้

• query (จําเป็น) สตริงข้อความที่จะค้นหา เช่น "ร้านอาหาร" หรือ "123 ถนนสีลม" ต้องเป็นชื่อสถานที่ ที่อยู่ หรือหมวดหมู่สถานที่ อินพุตประเภทอื่นๆ อาจทําให้เกิดข้อผิดพลาดได้ และไม่รับประกันว่าจะแสดงผลลัพธ์ที่ถูกต้อง บริการ Places จะแสดงผลการจับคู่ผู้สมัครตามสตริงนี้และเรียงลําดับผลการค้นหาตามความเกี่ยวข้องที่ผู้ใช้รับรู้ พารามิเตอร์นี้จะกลายเป็นตัวเลือกที่ไม่บังคับหากมีการใช้พารามิเตอร์ type ในคําขอการค้นหาด้วย
• ไม่บังคับ
  • openNow — ค่าบูลีนที่ระบุว่าบริการ Places ควรส่งคืนเฉพาะสถานที่ที่เปิดทําการ ณ เวลาที่ส่งคําค้นหา สถานที่ที่ไม่ระบุเวลาทําการในฐานข้อมูลของ Google Places จะไม่แสดง หากคุณใส่พารามิเตอร์นี้ในการค้นหา การตั้งค่า openNow เป็น false จะไม่มีผล
  • minPriceLevel และ maxPriceLevel — จํากัดผลลัพธ์เฉพาะสถานที่ภายในระดับราคาที่ระบุเท่านั้น ค่าที่ถูกต้องคืออยู่ในช่วงตั้งแต่ 0 (ประหยัดที่สุด) ถึง 4 (แพงที่สุด)
  • แบบใดแบบหนึ่งต่อไปนี้
    • bounds — ออบเจ็กต์ google.maps.LatLngBounds กําหนดสี่เหลี่ยมผืนผ้าที่ต้องการค้นหา หรือ
    • location และ radius — คุณอาจโน้มน้าวผลลัพธ์ที่จะเกิดขึ้นกับวงกลมที่ระบุได้โดยการส่งพารามิเตอร์ location และ radius วิธีนี้จะทําให้บริการ Places ต้องการแสดงผลลัพธ์ภายในแวดวงนั้น ผลการค้นหาที่อยู่นอกพื้นที่ที่กําหนดอาจยังแสดงผลอยู่ ตําแหน่งจะยึดออบเจ็กต์ google.maps.LatLng และรัศมีจะใช้จํานวนเต็มอย่างง่าย ซึ่งแสดงรัศมีของวงกลมเป็นหน่วยเมตร รัศมีสูงสุดที่อนุญาตคือ 50,000 เมตร
  • type — จํากัดผลลัพธ์เฉพาะสถานที่ที่ตรงกับประเภทที่ระบุไว้ ระบุได้เพียงประเภทเดียว (หากระบุมากกว่า 1 ประเภท ระบบจะไม่สนใจทุกประเภทที่ติดตามรายการแรก) ดูรายการประเภทที่รองรับ

นอกจากนี้คุณต้องส่งผ่านเมธอดเรียกกลับไปยัง textSearch() เพื่อจัดการออบเจ็กต์ผลลัพธ์และการตอบกลับของ google.maps.places.PlacesServiceStatus

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    query: 'restaurant'
  };

  service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

การตอบกลับการค้นหา

รหัสสถานะ

ออบเจ็กต์การตอบกลับ PlacesServiceStatus มีสถานะคําขอและอาจมีข้อมูลการแก้ไขข้อบกพร่องเพื่อช่วยให้คุณติดตามสาเหตุที่คําขอสถานที่ล้มเหลวได้ ค่าสถานะที่เป็นไปได้มีดังนี้

• INVALID_REQUEST: คําขอนี้ไม่ถูกต้อง
• OK: การตอบกลับมีผลลัพธ์ที่ถูกต้อง
• OVER_QUERY_LIMIT: หน้าเว็บเกินโควต้า คําขอ
• REQUEST_DENIED: หน้าเว็บไม่ได้รับอนุญาตให้ใช้ PlacesService
• UNKNOWN_ERROR: คําขอ PlacesService ไม่สามารถประมวลผลได้ เนื่องจากข้อผิดพลาดของเซิร์ฟเวอร์ คําขออาจประสบความสําเร็จหากลองอีกครั้ง
• ZERO_RESULTS: ไม่พบผลการค้นหาสําหรับคําขอนี้

ผลการค้นหาสถานที่

ฟังก์ชัน findPlace(), nearbySearch() และ textSearch() จะแสดงผลอาร์เรย์ของออบเจ็กต์ PlaceResult

ออบเจ็กต์ PlaceResult แต่ละรายการอาจมีพร็อพเพอร์ตี้ต่อไปนี้

• business_status บ่งบอกสถานะการดําเนินการของสถานที่ หากเป็นธุรกิจ ซึ่งสามารถมีค่าใดค่าหนึ่งต่อไปนี้
  • OPERATIONAL
  • CLOSED_TEMPORARILY
  • CLOSED_PERMANENTLY
  หากไม่มีข้อมูล ระบบจะไม่แสดงผล business_status
• formatted_address เป็นสตริงซึ่งมีที่อยู่ที่มนุษย์อ่านได้ของสถานที่นี้ ระบบจะส่งพร็อพเพอร์ตี้ formatted_address สําหรับการค้นหาข้อความเท่านั้น

  บ่อยครั้งที่ที่อยู่นี้เทียบเท่ากับที่อยู่ไปรษณีย์ โปรดทราบว่าบางประเทศ เช่น สหราชอาณาจักร ไม่อนุญาตการเผยแพร่ที่อยู่ทางไปรษณีย์จริง เนื่องจากมีข้อจํากัดด้านการอนุญาตให้ใช้สิทธิ

  ที่อยู่ที่จัดรูปแบบจะประกอบด้วยส่วนประกอบที่อยู่อย่างน้อย 1 รายการ ตัวอย่างเช่น ที่อยู่ "111 8th Avenue, New York, NY" ประกอบด้วยองค์ประกอบต่อไปนี้ "111" (หมายเลขถนน) "8th Avenue" (เส้นทาง) "นิวยอร์ก" (เมือง) และ "NY" (รัฐสหรัฐอเมริกา)

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

• geometry: ข้อมูลที่เกี่ยวข้องกับเรขาคณิตของสถานที่ ซึ่งรวมถึง
  • location ระบุละติจูดและลองจิจูดของสถานที่
  • viewport กําหนดวิวพอร์ตที่ต้องการบนแผนที่เมื่อดูสถานที่นี้
• permanently_closed (เลิกใช้งาน) เป็นแฟล็กบูลีนที่ระบุว่าสถานที่ปิดถาวรหรือชั่วคราว (ค่า true) อย่าใช้ permanently_closed โปรดใช้ business_status เพื่อดูสถานะการดําเนินงานของธุรกิจแทน
• plus_code (ดูรหัสสถานที่ตั้งและโค้ด Plus) เป็นการอ้างอิงตําแหน่งที่เข้ารหัสซึ่งมาจากพิกัดละติจูดและลองจิจูดที่แสดงถึงพื้นที่ นั่นคือ 1/8000 องศา 1/8000 องศาองศา (ประมาณ 14 ม. x 14 ม. ที่เส้นศูนย์สูตร) หรือต่ํากว่า Plus Code สามารถใช้แทนที่อยู่จริงในสถานที่ที่ไม่มีที่อยู่ได้ (ในกรณีที่อาคารไม่มีหมายเลขถนน หรือไม่มีชื่อถนน)

  Plus Code มีรูปแบบเป็นโค้ดสากลและรหัสผสม:

  • global_code คือรหัสพื้นที่ 4 อักขระและรหัสท้องถิ่น 6 อักขระขึ้นไป (849VCWC8+R9)
  • compound_code เป็นรหัสท้องถิ่น 6 ตัวขึ้นไปที่มีตําแหน่งที่อาจไม่เหมาะสม (CWC8+R9, Mountain View, CA, USA) อย่าแยกวิเคราะห์เนื้อหานี้แบบเป็นโปรแกรม
  โดยทั่วไประบบจะแสดงทั้งรหัสสากลและรหัสผสม อย่างไรก็ตาม หากผลลัพธ์อยู่ในสถานที่ตั้งระยะไกล (เช่น มหาสมุทรหรือทะเลทราย) อาจมีการส่งคืนเฉพาะรหัสสากล
• html_attributions: อาร์เรย์ของการระบุแหล่งที่มาที่คุณควรแสดงเมื่อแสดงผลการค้นหา แต่ละรายการในอาร์เรย์มีข้อความ HTML สําหรับการระบุแหล่งที่มาเดียว หมายเหตุ: เป็นการรวมการระบุแหล่งที่มาทั้งหมดสําหรับการตอบกลับการค้นหาทั้งหมด ออบเจ็กต์ PlaceResult ทั้งหมดในการตอบกลับจึงมีรายการการระบุแหล่งที่มาที่เหมือนกัน
• icon แสดงผล URL สําหรับไอคอน PNG สี 71px x 71px
• icon_mask_base_uri แสดงผล URL พื้นฐานสําหรับไอคอนที่ไม่มีสี ลบด้วยส่วนขยาย .svg หรือ .png
• icon_background_color แสดงรหัสสี HEX เริ่มต้นสําหรับหมวดหมู่สถานที่
• name: ชื่อสถานที่
• opening_hours อาจมีข้อมูลต่อไปนี้
  • open_now เป็นค่าบูลีนที่ระบุว่าสถานที่นี้เปิดในเวลาปัจจุบันหรือไม่ (เลิกใช้งานในไลบรารีสถานที่, Maps JavaScript API ให้ใช้ utc_offset_minutes แทน)
• place_id คือตัวระบุที่เป็นข้อความซึ่งระบุสถานที่ที่ไม่ซ้ํากัน หากต้องการดึงข้อมูลเกี่ยวกับสถานที่ ให้ส่งตัวระบุนี้ในคําขอรายละเอียดสถานที่ ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีอ้างอิงสถานที่ด้วยรหัสสถานที่
• rating มีข้อมูลคะแนนของสถานที่ตั้งแต่ 0.0 ถึง 5.0 ตามรีวิวของผู้ใช้แบบรวม
• types อาร์เรย์ของประเภทสําหรับสถานที่นี้ (เช่น ["political", "locality"] หรือ ["restaurant", "lodging"]) อาร์เรย์นี้อาจมีหลายค่าหรือว่างเปล่า อาจมีการเพิ่มค่าใหม่โดยไม่ต้องแจ้งให้ทราบล่วงหน้า ดูรายการประเภทที่รองรับ
• vicinity: ที่อยู่แบบง่ายของสถานที่ ซึ่งรวมถึงชื่อถนน หมายเลขถนน และย่าน แต่ไม่ใช่จังหวัด/รัฐ รหัสไปรษณีย์ หรือประเทศ เช่น สํานักงาน Google ในซิดนีย์ของ Google มีค่า vicinity เป็น 5/48 Pirrama Road, Pyrmont

การเข้าถึงผลลัพธ์เพิ่มเติม

โดยค่าเริ่มต้น การค้นหาสถานที่แต่ละแห่งจะแสดงผลลัพธ์สูงสุด 20 รายการต่อการค้นหา อย่างไรก็ตาม การค้นหาแต่ละครั้งจะแสดงผลลัพธ์ได้มากถึง 60 รายการโดยแบ่งออกเป็น 3 หน้า และจะมีหน้าเพิ่มเติมผ่านออบเจ็กต์ PlaceSearchPagination หากต้องการเข้าถึงหน้าเพิ่มเติม คุณต้องจับภาพออบเจ็กต์ PlaceSearchPagination ผ่านฟังก์ชันเรียกกลับ ออบเจ็กต์ PlaceSearchPagination กําหนดดังนี้

• hasNextPage พร็อพเพอร์ตี้บูลีนที่ระบุว่าอนุญาตให้มีผลลัพธ์เพิ่มเติมหรือไม่ trueเมื่อมีหน้าผลการค้นหาเพิ่มเติม
• nextPage() ฟังก์ชันที่จะส่งคืนชุดผลลัพธ์ถัดไป หลังจากทําการค้นหา คุณต้องรอ 2 วินาทีก่อนผลการค้นหาถัดไปจะพร้อมใช้งาน

หากต้องการดูผลลัพธ์ชุดถัดไป โปรดโทร nextPage ผลการค้นหาแต่ละหน้าจะต้องแสดงก่อนที่จะแสดงหน้าถัดไป โปรดทราบว่าการค้นหาแต่ละรายการจะนับเป็นคําขอ 1 รายการที่จะจํากัดการใช้งาน

ตัวอย่างด้านล่างแสดงวิธีดัดแปลงฟังก์ชันเรียกกลับเพื่อบันทึกออบเจ็กต์ PlaceSearchPagination เพื่อให้คุณออกคําขอการค้นหาหลายรายการได้

TypeScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon!,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name!,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

หมายเหตุ: อ่านคู่มือเกี่ยวกับการใช้ TypeScript และ Google Maps

JavaScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
index.js

หมายเหตุ: JavaScript จะรวบรวมจากข้อมูลโค้ด TypeScript

ดูตัวอย่าง

ลองใช้ตัวอย่าง

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell

รายละเอียดสถานที่

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

คําขอรายละเอียดสถานที่

ระบบจะขอรายละเอียดสถานที่ด้วยการเรียกเมธอด getDetails() ของบริการ

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

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

นอกจากนี้ยังต้องใช้เมธอดเรียกกลับซึ่งต้องจัดการรหัสสถานะที่ส่งผ่านในการตอบสนอง google.maps.places.PlacesServiceStatus และออบเจ็กต์ google.maps.places.PlaceResult

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

ดูตัวอย่าง

คุณสามารถขอplace_idสถานที่ได้แบบไม่มีค่าใช้จ่าย โดยการเรียกใช้ getDetails() และระบุเฉพาะช่อง place_id

ช่อง (รายละเอียดสถานที่)

พารามิเตอร์ fields จะใช้อาร์เรย์ของสตริง (ชื่อช่อง)

เราจะเลิกใช้งานช่อง Places opening_hours.open_now และ utc_offset ใน Places SDK สําหรับ iOS ตั้งแต่วันที่ 20 พฤศจิกายน 2019 เป็นต้นไป และจะเลิกใช้งานวันที่ 20 กุมภาพันธ์ 2021 ดูข้อมูลเพิ่มเติม

ใช้พารามิเตอร์ fields เพื่อระบุอาร์เรย์ของประเภทข้อมูลสถานที่ที่จะแสดง เช่น fields: ['address_component', 'opening_hours', 'geometry'] ใช้จุดเมื่อระบุค่าผสม เช่น opening_hours.weekday_text

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

พื้นฐาน

หมวดหมู่พื้นฐานจะมีช่องต่อไปนี้
address_component, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color,name, permanently_closed (เลิกใช้งาน), photo, place_id, plus_code, type, url, utc_offset, 2,2adr_address2,2}

ข้อมูลติดต่อ

หมวดหมู่รายชื่อติดต่อจะมีช่องต่อไปนี้
formatted_phone_number, international_phone_number, opening_hours, website

บรรยากาศ

หมวดหมู่บรรยากาศประกอบด้วยช่องต่อไปนี้ price_level, rating, reviews, user_ratings_total

ข้อควรระวัง: คําขอสถานที่และคําขอรายละเอียดสถานที่ไม่แสดงช่องเดียวกัน คําขอการค้นหาสถานที่จะแสดงชุดย่อยของช่องที่แสดงผลโดยคําขอรายละเอียดสถานที่ หากช่องค้นหาที่ต้องการไม่แสดงช่องที่คุณต้องการ คุณสามารถใช้การค้นหาสถานที่เพื่อรับ place_id แล้วใช้รหัสสถานที่ในการส่งคําขอรายละเอียดสถานที่

ดูข้อมูลเพิ่มเติมเกี่ยวกับช่องสถานที่ ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีการเรียกเก็บเงินคําขอข้อมูลสถานที่ได้ที่การใช้งานและการเรียกเก็บเงิน

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

คําตอบรายละเอียดสถานที่

รหัสสถานะ

ออบเจ็กต์การตอบกลับ PlacesServiceStatus มีสถานะคําขอและอาจมีข้อมูลการแก้ไขข้อบกพร่องเพื่อช่วยให้คุณติดตามสาเหตุที่คําขอรายละเอียดสถานที่ล้มเหลวได้ ค่าสถานะที่เป็นไปได้มีดังนี้

• INVALID_REQUEST: คําขอนี้ไม่ถูกต้อง
• OK: การตอบกลับมีผลลัพธ์ที่ถูกต้อง
• OVER_QUERY_LIMIT: หน้าเว็บเกินโควต้า คําขอ
• NOT_FOUND ไม่พบตําแหน่งที่อ้างอิงในฐานข้อมูลของ Places
• REQUEST_DENIED: หน้าเว็บไม่ได้รับอนุญาตให้ใช้ PlacesService
• UNKNOWN_ERROR: คําขอ PlacesService ไม่สามารถประมวลผลได้ เนื่องจากข้อผิดพลาดของเซิร์ฟเวอร์ คําขออาจประสบความสําเร็จหากลองอีกครั้ง
• ZERO_RESULTS: ไม่พบผลการค้นหาสําหรับคําขอนี้

ผลการค้นหารายละเอียดสถานที่

การเรียก getDetails() ที่สําเร็จจะแสดงผลออบเจ็กต์ PlaceResult ที่มีพร็อพเพอร์ตี้ต่อไปนี้

• address_components: อาร์เรย์ที่มีคอมโพเนนต์แยกต่างหากที่ใช้กับที่อยู่นี้

  โดยทั่วไป คอมโพเนนต์ที่อยู่แต่ละรายการจะมีช่องต่อไปนี้

  • types[] คืออาร์เรย์ที่ระบุประเภทของคอมโพเนนต์ที่อยู่ ดูรายการประเภทที่รองรับ
  • long_name คือคําอธิบายหรือข้อความแบบเต็มของคอมโพเนนต์ที่อยู่ที่ Geocoder แสดงผล
  • short_name เป็นชื่อย่อสําหรับคอมโพเนนต์ที่อยู่ (หากมี) เช่น คอมโพเนนต์ที่อยู่ของรัฐอะแลสกาอาจมี long_name เป็น "อะแลสกา" และ short_name ของ "AK" โดยใช้ตัวย่อ 2 ตัวอักษร

  ข้อเท็จจริงต่อไปนี้เกี่ยวกับอาร์เรย์ address_components[]

  • อาร์เรย์ของคอมโพเนนต์ที่อยู่อาจมีคอมโพเนนต์มากกว่า formatted_address
  • อาร์เรย์ไม่ได้รวมเอนทิตีทางการเมืองทั้งหมดที่มีที่อยู่ นอกเหนือจากเอนทิตีที่รวมอยู่ใน formatted_address หากต้องการเรียกเอนทิตีทางการเมืองทั้งหมดซึ่งมีที่อยู่หนึ่งๆ คุณควรใช้การเข้ารหัสภูมิศาสตร์แบบย้อนกลับ โดยส่งละติจูด/ลองจิจูดของที่อยู่เป็นพารามิเตอร์ไปยังคําขอ
  • และไม่รับประกันว่ารูปแบบการตอบกลับจะเหมือนเดิมระหว่างคําขอ โดยเฉพาะอย่างยิ่ง จํานวน address_components อาจแตกต่างกันไปตามที่อยู่ที่ขอและอาจเปลี่ยนแปลงได้เมื่อเวลาผ่านไปสําหรับที่อยู่เดียวกัน คอมโพเนนต์สามารถเปลี่ยนตําแหน่งในอาร์เรย์ ประเภทของคอมโพเนนต์สามารถเปลี่ยนได้ คอมโพเนนต์ใดอาจหายไปในการตอบสนองในภายหลัง
• business_status บ่งบอกสถานะการดําเนินการของสถานที่ หากเป็นธุรกิจ ซึ่งสามารถมีค่าใดค่าหนึ่งต่อไปนี้
  • OPERATIONAL
  • CLOSED_TEMPORARILY
  • CLOSED_PERMANENTLY
  หากไม่มีข้อมูล ระบบจะไม่แสดงผล business_status
• formatted_address: ที่อยู่ที่มนุษย์อ่านได้ของสถานที่นี้

  บ่อยครั้งที่ที่อยู่นี้เทียบเท่ากับที่อยู่ไปรษณีย์ โปรดทราบว่าบางประเทศ เช่น สหราชอาณาจักร ไม่อนุญาตการเผยแพร่ที่อยู่ทางไปรษณีย์จริง เนื่องจากมีข้อจํากัดด้านการอนุญาตให้ใช้สิทธิ

  ที่อยู่ที่จัดรูปแบบจะประกอบด้วยส่วนประกอบที่อยู่อย่างน้อย 1 รายการ ตัวอย่างเช่น ที่อยู่ "111 8th Avenue, New York, NY" ประกอบด้วยองค์ประกอบต่อไปนี้ "111" (หมายเลขถนน) "8th Avenue" (เส้นทาง) "นิวยอร์ก" (เมือง) และ "NY" (รัฐสหรัฐอเมริกา)

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

• formatted_phone_number: หมายเลขโทรศัพท์ของสถานที่ ซึ่งอยู่ในรูปแบบ การประชุมระดับภูมิภาคของหมายเลข
• geometry: ข้อมูลที่เกี่ยวข้องกับเรขาคณิตของสถานที่ ซึ่งรวมถึง
  • location ระบุละติจูดและลองจิจูดของสถานที่
  • viewport กําหนดวิวพอร์ตที่ต้องการบนแผนที่เมื่อดูสถานที่นี้
• permanently_closed (เลิกใช้งาน) เป็นแฟล็กบูลีนที่ระบุว่าสถานที่ปิดถาวรหรือชั่วคราว (ค่า true) อย่าใช้ permanently_closed โปรดใช้ business_status เพื่อดูสถานะการดําเนินงานของธุรกิจแทน
• plus_code (ดูรหัสสถานที่ตั้งและโค้ด Plus) เป็นการอ้างอิงตําแหน่งที่เข้ารหัสซึ่งมาจากพิกัดละติจูดและลองจิจูดที่แสดงถึงพื้นที่ นั่นคือ 1/8000 องศา 1/8000 องศาองศา (ประมาณ 14 ม. x 14 ม. ที่เส้นศูนย์สูตร) หรือต่ํากว่า Plus Code สามารถใช้แทนที่อยู่จริงในสถานที่ที่ไม่มีที่อยู่ได้ (ในกรณีที่อาคารไม่มีหมายเลขถนน หรือไม่มีชื่อถนน)

  Plus Code มีรูปแบบเป็นโค้ดสากลและรหัสผสม:

  • global_code คือรหัสพื้นที่ 4 อักขระและรหัสท้องถิ่น 6 อักขระขึ้นไป (849VCWC8+R9)
  • compound_code เป็นรหัสท้องถิ่น 6 ตัวขึ้นไปที่มีตําแหน่งที่อาจไม่เหมาะสม (CWC8+R9, Mountain View, CA, USA) อย่าแยกวิเคราะห์เนื้อหานี้แบบเป็นโปรแกรม
  โดยทั่วไประบบจะแสดงทั้งรหัสสากลและรหัสผสม อย่างไรก็ตาม หากผลลัพธ์อยู่ในสถานที่ตั้งระยะไกล (เช่น มหาสมุทรหรือทะเลทราย) อาจมีการส่งคืนเฉพาะรหัสสากล
• html_attributions: ข้อความการระบุแหล่งที่มาที่จะแสดงสําหรับผลการค้นหาสถานที่นี้
• icon: URL ไปยังทรัพยากรรูปภาพที่ใช้เพื่อแสดงถึงประเภทของสถานที่นี้ได้
• international_phone_number มีหมายเลขโทรศัพท์ของสถานที่นี้ในรูปแบบระหว่างประเทศ รูปแบบระหว่างประเทศมีรหัสประเทศและนําหน้าด้วยเครื่องหมายบวก (+) ตัวอย่างเช่น international_phone_number สําหรับสํานักงาน Google ที่ซิดนีย์ของ Google คือ [phone]
• name: ชื่อสถานที่
• utc_offset เลิกใช้งานแล้วในไลบรารี Places, Maps JavaScript API ให้ใช้ utc_offset_minutes แทน
• utc_offset_minutes มีจํานวนนาทีของเขตเวลาปัจจุบันของสถานที่นี้เป็นการชดเชยเวลาจาก UTC ตัวอย่างเช่น สําหรับสถานที่ในซิดนีย์ เวลาออมแสงออสเตรเลีย เวลานี้จะเป็น 660 (+11 ชั่วโมงจาก UTC) และสําหรับสถานที่ในแคลิฟอร์เนียนอกเวลาออมแสงจะเป็น -480 (-8 ชั่วโมงจาก UTC)
• opening_hours มีข้อมูลต่อไปนี้
  • open_now (เลิกใช้งานในไลบรารี Places, Maps JavaScript API ให้ใช้ opening_hours.isOpen() แทน ดูวิดีโอนี้เกี่ยวกับวิธีใช้ isOpen พร้อมรายละเอียดสถานที่) เป็นค่าบูลีนที่ระบุว่าสถานที่นี้เปิดในเวลาปัจจุบันหรือไม่
  • periods[] คืออาร์เรย์ของช่วงเวลาทําการที่ครอบคลุมทั้ง 7 วัน โดยเริ่มจากวันอาทิตย์และเรียงตามลําดับเวลา โดยแต่ละช่วงเวลาจะประกอบด้วยข้อมูลต่อไปนี้
    • open มีออบเจ็กต์วันที่และเวลาที่อธิบายถึงเวลาเปิดทําการของสถานที่ต่อไปนี้
      • day ตัวเลขตั้งแต่ 0–6 ตามวันในสัปดาห์ ตั้งแต่วันอาทิตย์ เช่น 2 หมายถึงวันอังคาร
      • time อาจมีช่วงเวลาของวันในรูปแบบ 24 ชั่วโมง Hhhmm (ค่าอยู่ในช่วง 0000–2359) ระบบจะรายงาน time ในเขตเวลาของสถานที่
    • close อาจมีออบเจ็กต์วันที่และเวลาหนึ่งคู่ที่อธิบายเมื่อสถานที่ปิด หมายเหตุ: หากสถานที่เปิดอยู่เสมอ ส่วน close จะหายไปจากการตอบกลับ แอปพลิเคชันอาจมีสถานะเปิดเป็น open เสมอ โดยมี day ที่มีค่าเป็น 0 และ time มีค่า 0000 และไม่มี close
  • weekday_text คืออาร์เรย์ของสตริง 7 สตริงที่เป็นตัวแทนเวลาทําการที่จัดรูปแบบสําหรับแต่ละวันของสัปดาห์ หากระบุพารามิเตอร์ language ในคําขอรายละเอียดสถานที่ บริการ Places จะจัดรูปแบบและเลือกเวลาทําการสําหรับภาษานั้นอย่างเหมาะสม ลําดับขององค์ประกอบในอาร์เรย์นี้ขึ้นอยู่กับพารามิเตอร์ language บางภาษาเริ่มต้นสัปดาห์ในวันจันทร์ ส่วนภาษาอื่นๆ จะเริ่มในวันอาทิตย์
• permanently_closed (เลิกใช้งาน) เป็นแฟล็กบูลีนที่ระบุว่าสถานที่ปิดถาวรหรือชั่วคราว (ค่า true) อย่าใช้ permanently_closed โปรดใช้ business_status เพื่อดูสถานะการดําเนินงานของธุรกิจแทน
• photos[]: อาร์เรย์ของออบเจ็กต์ PlacePhoto คุณใช้ PlacePhoto เพื่อรับรูปภาพด้วยเมธอด getUrl() ได้ หรือจะตรวจสอบออบเจ็กต์สําหรับค่าต่อไปนี้ก็ได้
  • height: ความสูงสูงสุดของรูปภาพเป็นพิกเซล
  • width: ความกว้างสูงสุดของรูปภาพเป็นพิกเซล
  • html_attributions: ข้อความการระบุแหล่งที่มาที่จะแสดงกับรูปภาพสถานที่นี้
• place_id: ตัวระบุข้อความที่ระบุสถานที่โดยไม่ซ้ํากันและใช้เพื่อเรียกข้อมูลเกี่ยวกับสถานที่ผ่านคําขอรายละเอียดสถานที่ ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีอ้างอิงสถานที่ด้วยรหัสสถานที่
• rating: คะแนนของที่พักจาก 0.0 ถึง 5.0 ซึ่งอิงตามรีวิวรวมของผู้ใช้
• reviews อาร์เรย์ของรีวิวสูงสุด 5 รายการ รีวิวแต่ละรายการประกอบด้วยหลายองค์ประกอบต่อไปนี้
  • aspects[] มีอาร์เรย์ของออบเจ็กต์ PlaceAspectRating แต่ละรายการจะมีการให้คะแนนแอตทริบิวต์เดียวของสถานประกอบการ ออบเจ็กต์แรกในอาร์เรย์ถือว่าเป็นแง่มุมหลัก PlaceAspectRating แต่ละรายการกําหนดดังนี้
    • type ชื่อของสิ่งที่มีการให้คะแนน ประเภทที่รองรับ ได้แก่ appeal, atmosphere, decor, facilities, food, overall, quality และ service
    • rating คะแนนของผู้ใช้สําหรับด้านนี้ตั้งแต่ 0 ถึง 3
  • author_name ชื่อของผู้ใช้ที่ส่งรีวิว รีวิวแบบไม่ระบุตัวตนจะมาจาก "ผู้ใช้ Google" หากกําหนดพารามิเตอร์ภาษาไว้ วลี "ผู้ใช้ Google" จะแสดงผลสตริงที่แปลแล้ว
  • author_url ไปยังโปรไฟล์ Google+ ของผู้ใช้ (หากมี)
  • language รหัสภาษา IETF ที่ระบุภาษาที่ใช้ในรีวิวของผู้ใช้ ช่องนี้มีแท็กภาษาหลักเท่านั้น และไม่มีแท็กรองที่แสดงประเทศหรือภูมิภาค เช่น รีวิวภาษาอังกฤษทั้งหมดติดแท็กเป็น "en" ไม่ใช่ "en-AU" หรือ "en-UK" เป็นต้น
  • rating คะแนนโดยรวมของผู้ใช้สําหรับสถานที่นี้ ซึ่งเป็นเลขจํานวนเต็มตั้งแต่ 1 ถึง 5
  • textรีวิวของผู้ใช้ รีวิวสถานที่ด้วย Google Places จะถือว่ารีวิวข้อความเป็นส่วนที่ไม่บังคับ ช่องนี้จึงอาจว่างเปล่า
• types อาร์เรย์ของประเภทสําหรับสถานที่นี้ (เช่น ["political", "locality"] หรือ ["restaurant", "lodging"]) อาร์เรย์นี้อาจมีหลายค่าหรือว่างเปล่า อาจมีการเพิ่มค่าใหม่โดยไม่ต้องแจ้งให้ทราบล่วงหน้า ดูรายการประเภทที่รองรับ
• url: URL ของหน้า Google อย่างเป็นทางการสําหรับสถานที่นี้ นี่คือหน้าเว็บของ Google ที่มีข้อมูลที่ดีที่สุดเกี่ยวกับสถานที่ แอปพลิเคชันต้องลิงก์หรือฝังหน้านี้ไว้ในหน้าจอใดๆ ที่แสดงผลการค้นหาโดยละเอียดเกี่ยวกับสถานที่ดังกล่าวแก่ผู้ใช้
• vicinity: ที่อยู่แบบง่ายของสถานที่ ซึ่งรวมถึงชื่อถนน หมายเลขถนน และย่าน แต่ไม่ใช่จังหวัด/รัฐ รหัสไปรษณีย์ หรือประเทศ เช่น สํานักงาน Google ในซิดนีย์ของ Google มีค่า vicinity เป็น 5/48 Pirrama Road, Pyrmont ระบบจะส่งพร็อพเพอร์ตี้ vicinity สําหรับการค้นหาใกล้เคียงเท่านั้น
• website แสดงเว็บไซต์ที่เชื่อถือได้ของสถานที่นี้ เช่น หน้าแรกของธุรกิจ

หมายเหตุ: การให้คะแนนหลายมิติข้อมูลอาจใช้ไม่ได้กับสถานที่บางแห่ง หากมีรีวิวน้อยเกินไป คําตอบของรายละเอียดจะมีคะแนนเดิมในสเกล 0.0 ถึง 5.0 (หากมี) หรือไม่มีการให้คะแนนเลย

อ้างอิงสถานที่ด้วยรหัสสถานที่

รหัสสถานที่เป็นข้อมูลอ้างอิงที่ไม่ซ้ําสําหรับสถานที่ใน Google Maps รหัสสถานที่พร้อมใช้งานสําหรับสถานที่ส่วนใหญ่ ซึ่งรวมถึงธุรกิจ จุดสังเกต สวนสาธารณะ และสี่แยก

หากต้องการใช้รหัสสถานที่ในแอป คุณต้องค้นหารหัสก่อน ซึ่งพร้อมให้ใช้งานใน PlaceResult ของคําขอการค้นหาสถานที่หรือรายละเอียด จากนั้นคุณจะสามารถใช้รหัสสถานที่นี้เพื่อค้นหารายละเอียดสถานที่ได้

หมายเหตุ:รหัสสถานที่ยังใช้งานได้ผ่าน Places API ด้วย รหัสสถานที่แห่งเดียวหมายถึงสถานที่แห่งเดียว แต่สถานที่หนึ่งมีรหัสสถานที่ได้หลายรหัส ดูข้อมูลเพิ่มเติมได้ที่ภาพรวมรหัสสถานที่

รหัสสถานที่ได้รับการยกเว้นจากข้อจํากัดการแคชที่ระบุไว้ในส่วนที่ 3.2.3(ก) ของข้อกําหนดในการให้บริการของ Google Maps Platform คุณจึงจัดเก็บค่ารหัสสถานที่ไว้ใช้ภายหลังได้ ดูแนวทางปฏิบัติแนะนําเกี่ยวกับการจัดเก็บรหัสสถานที่ได้ที่ภาพรวมรหัสสถานที่

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

  var service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

รูปภาพสถานที่

ฟีเจอร์สถานที่ของรูปภาพจะช่วยให้คุณเพิ่มเนื้อหาภาพถ่ายคุณภาพสูง ในเว็บไซต์ของคุณได้ บริการรูปภาพช่วยให้คุณเข้าถึงรูปภาพหลายล้านรูปที่จัดเก็บไว้ในฐานข้อมูลสถานที่และ Google+ Local เมื่อคุณได้รับข้อมูลสถานที่โดยใช้คําขอรายละเอียดสถานที่ ระบบจะส่งข้อมูลอ้างอิงรูปภาพสําหรับเนื้อหาภาพถ่ายที่เกี่ยวข้อง คําขอการค้นหาใกล้เคียงและการค้นหาข้อความจะแสดงการอ้างอิงรูปภาพรายการเดียวต่อสถานที่ด้วยเมื่อมีความเกี่ยวข้อง เมื่อใช้บริการรูปภาพ คุณจะสามารถเข้าถึงรูปภาพที่อ้างอิงและปรับขนาดรูปภาพเป็นขนาดที่ดีที่สุดสําหรับแอปพลิเคชัน

ระบบจะแสดงผลอาร์เรย์ของออบเจ็กต์ PlacePhoto เป็นส่วนหนึ่งของออบเจ็กต์ PlaceResult สําหรับคําขอ getDetails(), textSearch() หรือ nearbySearch() ที่ใช้กับ PlacesService

หมายเหตุ: จํานวนรูปภาพที่แสดงจะแตกต่างกันไปตามคําขอ

• การค้นหาใกล้ๆ หรือการค้นหาข้อความจะแสดงออบเจ็กต์ PlacePhoto ได้สูงสุด 1 รายการ
• คําขอรายละเอียดจะแสดงออบเจ็กต์ PlacePhoto ได้สูงสุด 10 รายการ

คุณขอ URL ของรูปภาพที่เกี่ยวข้องได้โดยเรียกเมธอด PlacePhoto.getUrl() และส่งออบเจ็กต์ PhotoOptions ที่ถูกต้อง ออบเจ็กต์ PhotoOptions ช่วยให้คุณระบุความสูงและความกว้างของรูปภาพสูงสุดที่ต้องการได้ หากคุณระบุค่าสําหรับทั้ง maxHeight และ maxWidth บริการรูปภาพจะปรับขนาดรูปภาพให้เล็กลงจากทั้ง 2 ขนาด ในขณะที่ยังคงอัตราส่วนเดิมไว้

ข้อมูลโค้ดต่อไปนี้ยอมรับออบเจ็กต์สถานที่และเพิ่มเครื่องหมายลงในแผนที่หากมีรูปภาพ ระบบจะแทนที่รูปภาพเครื่องหมายเริ่มต้นด้วยรูปภาพขนาดเล็ก

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35})
  });
}

รูปภาพที่มาจากบริการรูปภาพมีแหล่งที่มาจากหลายตําแหน่ง เช่น เจ้าของธุรกิจและรูปภาพที่ผู้ใช้ให้ไว้ ในกรณีส่วนใหญ่ คุณใช้รูปภาพเหล่านี้ได้โดยไม่ต้องระบุแหล่งที่มาหรือใส่การระบุแหล่งที่มาที่จําเป็นลงในรูปภาพ อย่างไรก็ตาม หากองค์ประกอบ photo ที่แสดงผลมีค่าในช่อง html_attributions คุณจะต้องใส่การระบุแหล่งที่มาเพิ่มเติมในแอปพลิเคชันได้ทุกที่ที่แสดงรูปภาพ