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

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

ภาพรวม

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

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

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

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

เปิดใช้ API

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

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

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

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

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

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

ดูข้อมูลเพิ่มเติมที่ ภาพรวมของไลบรารี

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

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

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

โควต้า

Places Library จะแชร์โควต้าการใช้งานกับ Places API ตามที่อธิบายไว้ในเอกสารประกอบเกี่ยวกับขีดจำกัดการใช้งานของ Places API

นโยบาย

การใช้ Places Library, Maps JavaScript API ต้องเป็นไปตามนโยบายที่อธิบายไว้สำหรับ Places API

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

เมื่อใช้บริการ Places คุณสามารถทำการค้นหาได้ดังต่อไปนี้:

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

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

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

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

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

  • query (ต้องระบุ) สตริงข้อความที่จะค้นหา เช่น "Restaurant" หรือ "123 Main Street" โดยต้องเป็นชื่อสถานที่ ที่อยู่ หรือหมวดหมู่ของสถานประกอบการ อินพุตประเภทอื่นๆ อาจทําให้เกิดข้อผิดพลาด และไม่รับประกันว่าจะส่งกลับผลลัพธ์ที่ถูกต้อง Places API จะแสดงผลตัวเลือกที่ตรงกันตามสตริงนี้และเรียงลำดับผลลัพธ์ตามความเกี่ยวข้องที่รับรู้ได้
  • fields (จำเป็น) ช่องอย่างน้อย 1 ช่องที่ระบุประเภทข้อมูลสถานที่ที่จะแสดงผล
  • locationBias (ไม่บังคับ) พิกัดที่กำหนดพื้นที่ที่จะค้นหา ซึ่งอาจเป็นอย่างใดอย่างหนึ่งต่อไปนี้
    • ชุดพิกัดละติจูด/ลองจิจูดที่ระบุเป็น LatLngLiteral หรือวัตถุ LatLng
    • ขอบเขตสี่เหลี่ยมผืนผ้า (คู่ละติจูด/ลองจิจูด 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 หรือวัตถุ LatLng
    • ขอบเขตสี่เหลี่ยมผืนผ้า (จุดละติจูด/ลองจิจูด 4 จุด หรือวัตถุ LatLngBounds)
    • รัศมี (หน่วยเป็นเมตร) ที่มีศูนย์กลางอยู่ที่ละติจูด/ลองจิจูด

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

ฟิลด์ (ดูวิธีการเกี่ยวกับสถานที่)

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

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

พื้นฐาน

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

การติดต่อ

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

บรรยากาศ

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

เมธอด findPlaceFromQuery() และ findPlaceFromPhoneNumber() ต่างก็ใช้ช่องชุดเดียวกันและสามารถแสดงช่องเดียวกันในคำตอบที่เกี่ยวข้อง

ตั้งค่าการให้น้ำหนักพิเศษของตำแหน่ง (ดูวิธีการเกี่ยวกับสถานที่)

ใช้พารามิเตอร์ locationBias เพื่อสร้างผลการค้นหาโปรดให้กับ "ค้นหาสถานที่" ในพื้นที่ใดพื้นที่หนึ่ง คุณตั้งค่า 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}}

คำขอการค้นหาใกล้เคียง

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

  • 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 Places Text Search เป็นบริการบนเว็บที่แสดงผลข้อมูลเกี่ยวกับกลุ่มสถานที่ตามสตริง เช่น "พิซซ่าในนิวยอร์ก" หรือ "ร้านรองเท้าใกล้ออตตาวา" บริการจะตอบกลับด้วยรายการสถานที่ที่ตรงกับสตริงข้อความและอคติของตำแหน่งที่ตั้งไว้ การตอบสนองการค้นหาจะรวมรายชื่อสถานที่ คุณส่งคำขอรายละเอียดสถานที่เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับสถานที่ในการตอบกลับได้

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

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

เมธอดนี้จะได้รับคำขอที่มีฟิลด์ต่อไปนี้

  • query (ต้องระบุ) สตริงข้อความที่จะค้นหา เช่น "Restaurant" หรือ "123 Main Street" ต้องเป็นชื่อสถานที่ ที่อยู่ หรือหมวดหมู่ของสถานประกอบการ อินพุตประเภทอื่นๆ อาจทําให้เกิดข้อผิดพลาด และไม่รับประกันว่าจะส่งกลับผลลัพธ์ที่ถูกต้อง บริการ 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" (เส้นทาง), "New York" (เมือง) และ "NY" (รัฐในสหรัฐอเมริกา)

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

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

    โค้ด Plus จะมีการจัดรูปแบบเป็นโค้ดส่วนกลางและโค้ดแบบผสม ดังนี้

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

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

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

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

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

ตัวอย่างด้านล่างแสดงวิธีแก้ไขฟังก์ชันเรียกกลับเพื่อจับภาพออบเจ็กต์ 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;

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;
ดูตัวอย่าง

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

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

นอกเหนือจากการระบุรายชื่อสถานที่ภายในพื้นที่แล้ว บริการ 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);
  }
}

ดูตัวอย่าง

ฟิลด์ (รายละเอียดสถานที่)

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

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

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

พื้นฐาน

หมวดหมู่พื้นฐานประกอบด้วยช่องต่อไปนี้
address_components, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color,name, permanently_closed (เลิกใช้งานแล้ว), photo, place_id, plus_code, type, {17/de}, utc_offset, Maps/ใน API urlutc_offset_minutesvicinity

การติดต่อ

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

บรรยากาศ

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

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

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

รหัสสถานะ

ออบเจ็กต์การตอบกลับ 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" (เส้นทาง), "New York" (เมือง) และ "NY" (รัฐในสหรัฐอเมริกา)

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

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

    โค้ด Plus จะมีการจัดรูปแบบเป็นโค้ดส่วนกลางและโค้ดแบบผสม ดังนี้

    • 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 ในซิดนีย์ ออสเตรเลียคือ +61 2 9374 4000
  • name: ชื่อสถานที่
  • utc_offset เลิกใช้งานแล้ว ใน Places Library, Maps JavaScript API ให้ใช้ utc_offset_minutes แทน
  • utc_offset_minutes มีจำนวนนาทีที่เขตเวลาปัจจุบันของสถานที่แห่งนี้ออฟเซ็ตจาก UTC เช่น สำหรับสถานที่ในซิดนีย์ ออสเตรเลีย ในช่วงเวลาออมแสงจะเท่ากับ 660 (+11 ชั่วโมงจาก UTC) และสำหรับสถานที่ในแคลิฟอร์เนียนอกเวลาออมแสงจะเท่ากับ -480 (-8 ชั่วโมงจาก UTC)
  • opening_hours ประกอบด้วยข้อมูลต่อไปนี้
    • open_now (เลิกใช้งานแล้ว ใน Places Library, Maps JavaScript API ให้ใช้ opening_hours.isOpen() แทน ดูวิธีใช้ isOpen พร้อมรายละเอียดสถานที่ในวิดีโอนี้) เป็นค่าบูลีนที่ระบุว่าสถานที่นี้เปิดในเวลาปัจจุบันหรือไม่
    • periods[] คืออาร์เรย์ของช่วงเวลาเปิดทำการที่ครอบคลุม 7 วัน โดยเริ่มตั้งแต่วันอาทิตย์ตามลำดับเวลา แต่ละระยะเวลาจะมีข้อมูลต่อไปนี้
      • open มีออบเจ็กต์แบบวันและเวลา 2 คู่ที่อธิบายเวลาที่สถานที่เปิด ดังนี้
        • day ตัวเลขตั้งแต่ 0–6 ที่ตรงกับวันของสัปดาห์ โดยเริ่มจากวันอาทิตย์ เช่น 2 หมายถึงวันอังคาร
        • time อาจมีเวลาของวันในรูปแบบ 24 ชั่วโมง hhmm (ค่าจะอยู่ในช่วง 0000-2359) ระบบจะรายงาน time ในเขตเวลาของสถานที่
      • close อาจมีออบเจ็กต์แบบวันและเวลา 2 ประเภทที่อธิบายเมื่อสถานที่ปิด หมายเหตุ: หากสถานที่เปิดตลอดเวลา คำตอบจะไม่มีส่วน 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 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 ในซิดนีย์ ในออสเตรเลียมีค่า vicinity เป็น 5/48 Pirrama Road, Pyrmont ระบบจะแสดงพร็อพเพอร์ตี้ vicinity สำหรับการค้นหาใกล้เคียงเท่านั้น
  • website แสดงรายชื่อเว็บไซต์ที่เชื่อถือได้ของสถานที่นี้ เช่น หน้าแรกของธุรกิจ

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

ใช้คอมโพเนนต์ภาพรวมสถานที่

หมายเหตุ: ตัวอย่างนี้ใช้ไลบรารีโอเพนซอร์ส โปรดดู README สำหรับการสนับสนุนและความคิดเห็นเกี่ยวกับไลบรารี

ลองใช้คอมโพเนนต์เว็บ ใช้ คอมโพเนนต์เว็บภาพรวมสถานที่เพื่อรับรายละเอียดสถานที่ด้วยการนำเสนอภาพ

รูปภาพแสดงรูปแบบต่างๆ ของคอมโพเนนต์ภาพรวมสถานที่ที่มีขนาดเล็ก เล็ก กลาง ใหญ่ และใหญ่มาก โดยอิงตามช่องขนาดที่ผู้ใช้ป้อน
ภาพที่ 1: ข้อมูลรายละเอียดสถานที่ที่มีขนาด 5 แบบ

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

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

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

รหัสสถานที่ได้รับการยกเว้นจากข้อจํากัดการแคชที่ระบุไว้ในส่วนที่ 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);

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

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

ระบบจะแสดงผลอาร์เรย์ของออบเจ็กต์ 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 คุณต้องระบุการระบุแหล่งที่มาเพิ่มเติมในแอปพลิเคชันด้วยทุกที่ที่แสดงรูปภาพ