מעבר לממשק החדש של חיפוש המקומות

בדף הזה נסביר את ההבדלים בין התכונות של חיפוש מקומות מבוסס-טקסט בכיתה Place (חדשה) לבין התכונות בכיתה PlacesService (מהדור קודם), ונספק כמה קטעי קוד להשוואה.

ל-PlacesService הקודם יש את שיטות החיפוש הבאות שמבוססות על טקסט:

• השיטה findPlaceFromQuery(), שמקבלת שאילתת טקסט ומחזירה תוצאה של מקום אחד, ותומכת בשימוש בשדות של נתוני מקומות.
• השיטה findPlaceFromPhoneNumber() שמאפשרת לחפש מקום באמצעות מספר טלפון, ותומכת בשימוש בשדות של נתוני מקומות.
• השיטה textSearch(), שמקבלת שאילתת טקסט ומחזירה רשימה של תוצאות של מקומות. textSearch() הוא תג ישן יותר, ואין בו תמיכה בשימוש בשדות של נתוני מקומות.

בכיתה החדשה Place יש את השיטה Place.searchByText(), שמאפשרת לחפש מקומות באמצעות שאילתה בטקסט או מספר טלפון, ולהתאים אישית את החיפושים באמצעות מבחר מורחב של שדות נתונים של מקומות וסוגים של מקומות שמתעדכנים באופן קבוע.

בטבלה הבאה מפורטים חלק מההבדלים העיקריים בין שיטות החיפוש של מקומות בין הכיתה Place לבין PlacesService:

PlacesService (דור קודם)	Place (חדש)
findPlaceFromQuery() findPlaceFromPhoneNumber()	searchByText()
FindPlaceFromQueryRequest FindPlaceFromPhoneNumberRequest	SearchByTextRequest
אפשרויות שאילתה מוגבלות.	אפשרויות שאילתות נרחבות יותר.
צריך להשתמש בפונקציית קריאה חוזרת כדי לטפל באובייקט התוצאות ובתגובה google.maps.places.PlacesServiceStatus.	משתמשת ב-Promises ופועלת באופן אסינכרוני.
צריך לסמן את התיבה PlacesServiceStatus.	אין צורך בבדיקת סטטוס, אפשר להשתמש בטיפול שגיאות רגיל.
יש תמיכה רק בהטיה לפי מיקום.	יש תמיכה בהטיה לפי מיקום ובהגבלת מיקום.
שדות של נתוני מיקום מעוצבים לפי פורמט snake case.	שדות של נתוני מקומות מוגדרים בפורמט camel case.
הפונקציה מחזירה תוצאה של מקום אחד.	הפונקציה מחזירה עד 20 תוצאות של מקומות.
מוגבלת לקבוצה קבועה של סוגים של מקומות ושדות של נתוני מקומות.	מציעים מבחר מורחב של סוגים של מקומות ושדות של נתוני מקומות שמתעדכנים באופן קבוע.
textSearch()	searchByText()
הפונקציה מחזירה את כל שדות הנתונים הזמינים (קבוצת משנה של השדות הנתמכים). אי אפשר להגביל אותה לשדות ספציפיים.	הפונקציה מחזירה רק את שדות נתוני המיקום המבוקשים.

השוואת קוד

בקטע הזה נסביר את ההבדלים בין שירות Places לבין הכיתה Place באמצעות השוואה בין הקוד של שיטות החיפוש בטקסט. בקטעי הקוד מוצג הקוד שנדרש בכל ממשק API כדי לשלוח בקשת חיפוש מבוססת-טקסט.

שירות Places (דור קודם)

קטע הקוד הבא מראה איך משתמשים ב-method‏ findPlaceFromQuery() כדי לחפש מקום. הבקשה היא סנכרונית וכוללת בדיקה מותנית של PlacesServiceStatus. שדות נתוני המיקום הנדרשים מצוינים בגוף הבקשה, שמוגדר לפני שליחת הבקשה בפועל.

function findPlaces() {
  const request = {
    query: "Museum of Contemporary Art Australia",
    fields: ["name", "geometry"],
  };

  // Create an instance of PlacesService.
  service = new google.maps.places.PlacesService(map);

  // Make a findPlaceFromQuery request.
  service.findPlaceFromQuery(request, (results, status) => {
    let place = results[0];
    if (status === google.maps.places.PlacesServiceStatus.OK && results) {
      if (!place.geometry || !place.geometry.location) return;

      const marker = new google.maps.Marker({
        map,
        position: place.geometry.location,
      });
      map.setCenter(place.geometry.location);
    }
  });
}

מידע נוסף

• הקוד המלא לדוגמה
• לעיון במסמכי התיעוד
• מידע על ממשק FindPlaceFromQueryRequest

חיפוש טקסט (חדש)

קטע הקוד הבא מראה איך משתמשים בשיטה searchByText() כדי לחפש מקומות. הבקשה היא אסינכרונית ואין צורך בבדיקה של סטטוס (אפשר להשתמש בטיפול שגיאות רגיל). בדוגמה הזו, הבקשה כוללת maxResultCount של 8 (הערך חייב להיות בין 1 ל-20). הפונקציה הזו עוברת על התוצאות ומוסיפה סמן לכל אחת מהן, תוך התאמת גבולות המפה לפי המיקום של הסימנים. מכיוון ששיטת searchByText() משתמשת באופרטור await, אפשר להשתמש בה רק בתוך פונקציית async.

async function findPlaces() {
  // Define a request.
  // The `fields` property is required; all others are optional.
  const request = {
    fields: ["displayName", "location", "businessStatus"],
    textQuery: "Tacos in Mountain View",
    includedType: "restaurant",
    locationBias: { lat: 37.4161493, lng: -122.0812166 },
    isOpenNow: true,
    language: "en-US",
    maxResultCount: 8,
    minRating: 3.2,
    region: "us",
    useStrictTypeFiltering: false,
  };

  // Call searchByText passing the request.
  const { places } = await google.maps.places.Place.searchByText(request);

  // Add a marker for each result.
  if (places.length) {
    const bounds = new google.maps.LatLngBounds();

    places.forEach((place) => {
      const markerView = new google.maps.marker.AdvancedMarkerElement({
        map,
        position: place.location,
        title: place.displayName,
      });

      bounds.extend(place.location);
      console.log(place);
    });
    map.fitBounds(bounds);
  } else {
    console.log("No results");
  }
}

השיטה searchByText() תומכת באפשרויות בקשה רבות יותר בהשוואה לגרסה הקודמת, כולל:

• includedType, שמאפשרת להגביל את החיפושים לסוג מקום ספציפי.
• isOpenNow, שמאפשרת להגביל את החיפושים כך שיחזירו רק מקומות פתוחים.
• minRating, שמאפשר לסנן תוצאות מתחת למגבלה שצוינה (לדוגמה, להציג רק מקומות עם שלוש כוכבים או יותר).
• locationRestriction, שמשמיט תוצאות מחוץ למיקום שצוין (יש תמיכה גם ב-locationBias).

מידע נוסף

• הקוד המלא לדוגמה
• מידע נוסף זמין במסמכי התיעוד של חיפוש טקסט (חדש)
• מידע נוסף זמין במסמך העזרה searchByText()