ספריית מקומות

מפתחים באזור הכלכלי האירופי (EEA)

סקירה כללית

הפונקציות בספריית המקומות ב-Maps JavaScript API מאפשרות לאפליקציה לחפש מקומות (שמוגדרים ב-API הזה כעסקים, מיקומים גיאוגרפיים או נקודות עניין בולטות) שנמצאים באזור מוגדר, כמו הגבולות של מפה או סביב נקודה קבועה.

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

תחילת העבודה

אם אתם לא מכירים את Maps JavaScript API או את JavaScript, מומלץ לעיין ב-JavaScript ובמאמר קבלת מפתח API לפני שמתחילים.

טעינת הספרייה

שירות Places הוא ספרייה עצמאית, נפרדת מהקוד הראשי של Maps JavaScript API. כדי להשתמש בפונקציונליות שכלולה בספרייה הזו, קודם צריך לטעון אותה באמצעות הפרמטר libraries בכתובת ה-URL ההתחלתית של 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 אחד או יותר, או ל-SDK אחד או יותר. בקשות ל-API או ל-SDK שמשויכות למפתח ה-API יעובדו. בקשות ל-API או ל-SDK שלא משויכים למפתח ה-API ייכשלו. כדי להגביל מפתח API לשימוש עם ספריית המקומות ב-Maps JavaScript API:
  1. נכנסים למסוף Google Cloud.
  2. לוחצים על התפריט הנפתח של הפרויקט ובוחרים את הפרויקט שמכיל את מפתח ה-API שרוצים לאבטח.
  3. לוחצים על כפתור התפריט ובוחרים באפשרות Google Maps Platform > Credentials.
  4. בדף Credentials, לוחצים על השם של מפתח ה-API שרוצים לאבטח.
  5. בדף Restrict and rename API key, מגדירים את ההגבלות:
    • הגבלות על ממשקי API
      • לוחצים על הגבלת המפתח.
      • לוחצים על Select APIs ובוחרים באפשרויות Maps JavaScript API ו-Places API (Legacy).
        (אם אחד מממשקי ה-API לא מופיע ברשימה, צריך להפעיל אותו).
  6. לוחצים על שמירה.

מגבלות שימוש ומדיניות

מכסות

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

מדיניות

השימוש בספריית המקומות ב-Maps JavaScript API צריך להיות בהתאם למדיניות שמתוארת לגבי Places API.

חיפושי מקומות

בעזרת שירות Places, אתם יכולים לבצע את סוגי החיפושים הבאים:

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

בקשות של "חיפוש מקום" (גרסה קודמת)

בקשה לחיפוש מקום מאפשרת לחפש מקום באמצעות שאילתת טקסט או מספר טלפון. יש שני סוגים של בקשות Find Place:

חיפוש מקום לפי שאילתה

השיטה "חיפוש מקום לפי שאילתה" מקבלת קלט טקסט ומחזירה מקום. הקלט יכול להיות כל סוג של נתוני מקום, למשל שם או כתובת של עסק. כדי לשלוח בקשה מסוג Find Place from Query, מפעילים את השיטה findPlaceFromQuery() של PlacesService, שמקבלת את הפרמטרים הבאים:

  • ‫query (חובה) מחרוזת הטקסט לחיפוש, לדוגמה: "מסעדה" או "רחוב הרצל 123". השאילתה צריכה להיות שם של מקום, כתובת או קטגוריה של עסקים. כל סוג אחר של קלט עלול לגרום לשגיאות, ואין ערובה לכך שיתקבלו תוצאות תקינות. ‫Places API יחזיר התאמות אפשריות על סמך המחרוזת הזו ויסדר את התוצאות לפי הרלוונטיות המשוערת שלהן.
  • ‫fields (חובה) שדה אחד או יותר שמציינים את סוגי הנתונים של המקום שרוצים להחזיר.
  • locationBias (אופציונלי) קואורדינטות שמגדירות את האזור לחיפוש. הערך יכול להיות אחד מהבאים:
    • קבוצה של קואורדינטות של קו רוחב/אורך שצוינו בתור LatLngLiteral או אובייקט LatLng
    • גבולות מלבניים (שני זוגות של קווי רוחב/אורך, או אובייקט LatLngBounds)
    • רדיוס (במטרים) שמרכזו בקו רוחב/קו אורך

צריך גם להעביר שיטת קריאה חוזרת (callback) אל findPlaceFromQuery(), כדי לטפל באובייקט התוצאות ובתגובה של google.maps.places.PlacesServiceStatus.

בדוגמה הבאה מוצגת קריאה ל-findPlaceFromQuery(), חיפוש של "Museum of Contemporary Art Australia" והכללת השדות 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);
    }
  });
}
 לצפייה בדוגמה

חיפוש מקום לפי מספר טלפון

השיטה "חיפוש מקום לפי מספר טלפון" מקבלת מספר טלפון ומחזירה מקום. כדי לשלוח בקשה לחיפוש מקום לפי מספר טלפון, מפעילים את ה-method‏ findPlaceFromPhoneNumber() של PlacesService, שמקבלת את הפרמטרים הבאים:

  • ‫phoneNumber (חובה) מספר טלפון בפורמט E.164.
  • ‫fields (חובה) שדה אחד או יותר שמציינים את סוגי הנתונים של המקום שרוצים להחזיר.
  • ‫locationBias (אופציונלי) קואורדינטות שמגדירות את האזור לחיפוש. הפרטים יכולים להיות:
    • קבוצה של קואורדינטות של קו רוחב/אורך שצוינו בתור LatLngLiteral או אובייקט LatLng
    • גבולות מלבניים (ארבע נקודות של קו רוחב/קו אורך, או אובייקט LatLngBounds)
    • רדיוס (במטרים) שמרכזו בקו רוחב/קו אורך

צריך גם להעביר שיטת קריאה חוזרת (callback) אל findPlaceFromPhoneNumber(), כדי לטפל באובייקט התוצאות ובתגובה של google.maps.places.PlacesServiceStatus.

שדות (שיטות של Find Place)

משתמשים בפרמטר fields כדי לציין מערך של סוגי נתונים של מקומות שרוצים להחזיר. לדוגמה: fields: ['formatted_address', 'opening_hours', 'geometry']. צריך להשתמש בנקודה כשמציינים ערכים מורכבים. לדוגמה: opening_hours.weekday_text.

השדות תואמים לתוצאות של חיפוש מקומות, והם מחולקים לשלוש קטגוריות חיוב: Basic,‏ Contact ו-Atmosphere. שדות בסיסיים מחויבים בתעריף הבסיס, ללא חיובים נוספים. השדות "פרטים ליצירת קשר" ו"אווירה" מחויבים בתעריף גבוה יותר. למידע נוסף, ראו גיליון התמחור. השדה Attributions (html_attributions) תמיד מוחזר בכל קריאה, גם אם לא ביקשתם אותו.

Basic

הקטגוריה "בסיסי" כוללת את השדות הבאים:
business_status, formatted_address, geometry, icon,icon_mask_base_uri, icon_background_color, name, permanently_closed (הוצא משימוש), photos, place_id, plus_code, types

יצירת קשר

הקטגוריה Contact כוללת את השדה הבא: opening_hours
(הוצא משימוש בספריית המקומות, Maps JavaScript API. כדי לקבל את התוצאות של opening_hours, צריך להשתמש בבקשה מסוג Place Details.

אווירה

הקטגוריה Atmosphere כוללת את השדות הבאים: price_level, ‏ rating, ‏ user_ratings_total

השיטות findPlaceFromQuery() ו-findPlaceFromPhoneNumber() מקבלות את אותה קבוצת שדות, ויכולות להחזיר את אותם שדות בתשובות שלהן.

הגדרת העדפת מיקום (שיטות Find Place)

כדי שהתוצאות של "חיפוש מקום" יתמקדו באזור מסוים, משתמשים בפרמטר 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 – ורדיוס, שנמדד במטרים.

כדי להתחיל חיפוש של מקומות בסביבה, שולחים קריאה ל-method‏ nearbySearch() של PlacesService, שמחזירה מערך של אובייקטים מסוג PlaceResult. שימו לב שהשיטה nearbySearch() מחליפה את השיטה search() החל מגרסה 3.9.

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

השיטה הזו מקבלת בקשה עם השדות הבאים:

  • אחת מהאפשרויות הבאות:
    • ‫bounds, שצריך להיות אובייקט google.maps.LatLngBounds שמגדיר את אזור החיפוש המלבני. המרחק המקסימלי שנתמך באלכסון של אזור הגבולות הוא בערך 100,000 מטרים.
    • ‫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.
  • ‫type – הגבלת התוצאות למקומות שתואמים לסוג שצוין. אפשר לציין רק סוג אחד (אם מציינים יותר מסוג אחד, המערכת מתעלמת מכל הסוגים שמופיעים אחרי הרשומה הראשונה). לרשימת הסוגים הנתמכים

צריך גם להעביר שיטת קריאה חוזרת (callback) אל 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 הוא שירות אינטרנט שמחזיר מידע על קבוצת מקומות על סמך מחרוזת – לדוגמה, "פיצה בניו יורק" או "חנויות נעליים ליד אוטווה". השירות מחזיר רשימה של מקומות שתואמים למחרוזת הטקסט ולהעדפת המיקום שהוגדרה. התגובה לחיפוש תכלול רשימה של מקומות. כדי לקבל מידע נוסף על כל אחד מהמקומות שבתגובה, אתם יכולים לשלוח בקשה ל-Place Details.

כדי להתחיל חיפושי טקסט, צריך להפעיל את ה-method ‏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 שמגדיר את אזור החיפוש המלבני. המרחק האלכסוני המקסימלי שנתמך לאזור הגבולות הוא כ-100,000 מטרים.
      • ‫location ו-radius – אפשר להטות את התוצאות למעגל מסוים על ידי העברת הפרמטרים location ו-radius. ‫ההגדרה הזו תנחה את שירות Places להעדיף להציג תוצאות בתוך המעגל הזה. יכול להיות שעדיין יוצגו תוצאות מחוץ לאזור שהוגדר. המיקום מקבל אובייקט google.maps.LatLng, והרדיוס מקבל מספר שלם פשוט שמייצג את רדיוס המעגל במטרים. הרדיוס המקסימלי המותר הוא 50,000 מטרים.
    • ‫type – הגבלת התוצאות למקומות שתואמים לסוג שצוין. אפשר לציין רק סוג אחד (אם צוין יותר מסוג אחד, המערכת תתעלם מכל הסוגים אחרי הרשומה הראשונה). לרשימת הסוגים הנתמכים

צריך גם להעביר שיטת קריאה חוזרת (callback) אל 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 מוחזר רק בחיפוש טקסט.

    בדרך כלל הכתובת הזו זהה לכתובת למשלוח דואר. שימו לב שבמדינות מסוימות, כמו בריטניה, אסור להפיץ כתובות דואר אמיתיות בגלל הגבלות רישוי.

    הכתובת המעוצבת מורכבת באופן לוגי מרכיב כתובת אחד או יותר. לדוגמה, הכתובת "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 (ראו Open Location Code ו-plus codes) הוא מיקום מקודד, שנגזר מקואורדינטות של קו רוחב וקו אורך, שמייצג אזור: 1/8000 של מעלה על 1/8000 של מעלה (בערך 14 מ' על 14 מ' בקו המשווה) או קטן יותר. אפשר להשתמש ב-Plus Codes במקום כתובות רחוב במקומות שבהם אין כתובות (למשל, במקומות שבהם הבניינים לא ממוספרים או שלרחובות אין שמות).

    ה-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 מחזירה את קוד הצבע ההקסדצימלי שמוגדר כברירת מחדל לקטגוריה של המקום.
  • ‫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 בסידני, אוסטרליה, יש ערך vicinity של 5/48 Pirrama Road, Pyrmont.

גישה לתוצאות נוספות

כברירת מחדל, כל חיפוש מקומות מחזיר עד 20 תוצאות לכל שאילתה. עם זאת, כל חיפוש יכול להחזיר עד 60 תוצאות, שמחולקות לשלושה דפים. אפשר להשתמש באובייקט PlaceSearchPagination כדי להציג דפים נוספים. כדי לגשת לדפים נוספים, צריך לתעד את האובייקט PlaceSearchPagination באמצעות פונקציית קריאה חוזרת. האובייקט PlaceSearchPagination מוגדר כך:

  • ‫hasNextPage מאפיין בוליאני שמציין אם יש תוצאות נוספות. true כשיש דף תוצאות נוסף.
  • ‫nextPage() פונקציה שתחזיר את קבוצת התוצאות הבאה. אחרי שמבצעים חיפוש, צריך להמתין שתי שניות לפני שהדף הבא של התוצאות יהיה זמין.

כדי לראות את קבוצת התוצאות הבאה, צריך להפעיל את 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 יכול גם להחזיר מידע מפורט על מקום ספציפי. אחרי שמקום מוחזר בתגובה לחיפוש מקומות, אפשר להשתמש במזהה המקום שלו כדי לבקש פרטים נוספים על המקום, כמו הכתובת המלאה, מספר הטלפון, דירוג המשתמשים וביקורות וכו'.

בקשות ל-Place Details

כדי לבקש Place Details, צריך להפעיל את השיטה getDetails() של השירות.

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

השיטה הזו מקבלת בקשה שמכילה את המזהה placeId של המקום, ושדות שמציינים אילו סוגים של נתוני מקומות להחזיר. איך מפנים למקום באמצעות מזהה מקום

היא גם מקבלת שיטת קריאה חוזרת (callback), שצריכה לטפל בקוד הסטטוס שמועבר בתגובה של 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.

השדות תואמים לתוצאות של Place Details, והם מחולקים לשלוש קטגוריות חיוב: Basic,‏ Contact ו-Atmosphere. שדות בסיסיים מחויבים בתעריף הבסיס, ללא חיובים נוספים. השדות "פרטים ליצירת קשר" ו"אווירה" מחויבים בתעריף גבוה יותר. למידע נוסף, ראו גיליון התמחור. המאפיינים (html_attributions) תמיד מוחזרים בכל קריאה, גם אם לא ביקשתם אותם.

Basic

הקטגוריה Basic כוללת את השדות הבאים:
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, url, utc_offset (הוצא משימוש בספריית המקומות, Maps JavaScript API), utc_offset_minutes, vicinity

יצירת קשר

הקטגוריה "איש קשר" כוללת את השדות הבאים:
formatted_phone_number, international_phone_number, opening_hours, website

אווירה

הקטגוריה Atmosphere כוללת את השדות הבאים: price_level, ‏ rating, ‏ reviews,‏ user_ratings_total

מידע נוסף על שדות של מקומות למידע נוסף על החיוב של בקשות נתונים של מקומות, ראו שימוש וחיוב.

תגובות של Place Details

קודי סטטוס

האובייקט PlacesServiceStatus בתגובה מכיל את סטטוס הבקשה, ויכול להיות שהוא יכיל מידע על תוצאות ניפוי הבאגים שיעזור לכם לעקוב אחרי למה הבקשה ל-Place Details נכשלה. ערכי הסטטוס האפשריים הם:

  • ‫INVALID_REQUEST: הבקשה לא תקינה.
  • ‫OK: התגובה מכילה תוצאה תקינה.
  • OVER_QUERY_LIMIT: דף האינטרנט חרג ממכסת הבקשות שלו.
  • NOT_FOUND המיקום שצוין לא נמצא במסד הנתונים של Places.
  • ‫REQUEST_DENIED: לדף האינטרנט אין הרשאה להשתמש ב-PlacesService.
  • ‫UNKNOWN_ERROR: לא ניתן היה לעבד את הבקשה של PlacesService בגלל שגיאה בחיבור לשרת. יכול להיות שהבקשה תצליח אם תנסו שוב.
  • ‫ZERO_RESULTS: לא נמצאה תוצאה לבקשה הזו.

תוצאות של Place Details

קריאה מוצלחת ל-getDetails() מחזירה אובייקט PlaceResult עם המאפיינים הבאים:

  • ‫address_components: מערך שמכיל את הרכיבים הנפרדים שרלוונטיים לכתובת הזו.

    כל רכיב כתובת מכיל בדרך כלל את השדות הבאים:

    • ‫types[] הוא מערך שמציין את הסוג של רכיב הכתובת. יכול להיות שרכיב הכתובת יכלול מערך סוגים ריק אם אין סוגים ידועים לרכיב הכתובת הזה. יכול להיות שה-API יוסיף ערכי סוג חדשים לפי הצורך. מידע נוסף זמין במאמר סוגי כתובות וסוגי רכיבים של כתובות.
    • ‫long_name הוא תיאור הטקסט המלא או השם של רכיב הכתובת, כפי שהוחזר על ידי הכלי להמרת כתובות לקואורדינטות (geocoder).
    • ‫short_name הוא שם טקסטואלי מקוצר של רכיב הכתובת, אם הוא זמין. לדוגמה, רכיב כתובת של מדינת אלסקה יכול לכלול long_name של "אלסקה" ו-short_name של "AK" באמצעות קיצור הדואר בן 2 האותיות.

    שימו לב לעובדות הבאות לגבי המערך address_components[]:

    • מערך רכיבי הכתובת יכול להכיל יותר רכיבים מאשר formatted_address.
    • המערך לא בהכרח כולל את כל הישויות הפוליטיות שמכילות כתובת, מלבד אלה שנכללות ב-formatted_address. כדי לאחזר את כל הישויות הפוליטיות שמכילות כתובת ספציפית, צריך להשתמש בהמרת קואורדינטות לכתובות (reverse geocoding) ולהעביר את קו הרוחב/קו האורך של הכתובת כפרמטר לבקשה.
    • אין ערובה לכך שפורמט התגובה יישאר זהה בין הבקשות. במיוחד, מספר ה-address_components משתנה בהתאם לכתובת המבוקשת ויכול להשתנות עם הזמן עבור אותה כתובת. רכיב יכול לשנות את המיקום שלו במערך. סוג הרכיב יכול להשתנות. יכול להיות שרכיב מסוים לא יופיע בתגובה מאוחרת יותר.
  • business_status מציין את סטטוס הפעילות של המקום, אם מדובר בעסק. הוא יכול להכיל אחד מהערכים הבאים:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    אם אין נתונים, business_status לא מוחזר.
  • ‫formatted_address: הכתובת של המקום הזה, בפורמט שקריא לאנשים.

    בדרך כלל הכתובת הזו זהה לכתובת למשלוח דואר. שימו לב שבמדינות מסוימות, כמו בריטניה, אסור להפיץ כתובות דואר אמיתיות בגלל הגבלות רישוי.

    הכתובת המעוצבת מורכבת באופן לוגי מרכיב כתובת אחד או יותר. לדוגמה, הכתובת "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 (ראו Open Location Code ו-plus codes) הוא מיקום מקודד, שנגזר מקואורדינטות של קו רוחב וקו אורך, שמייצג אזור: 1/8000 של מעלה על 1/8000 של מעלה (בערך 14 מ' על 14 מ' בקו המשווה) או קטן יותר. אפשר להשתמש ב-Plus Codes במקום כתובות רחוב במקומות שבהם אין כתובות (למשל, במקומות שבהם הבניינים לא ממוספרים או שלרחובות אין שמות).

    ה-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 בסידני, אוסטרליה הוא +61 2 9374 4000.
  • ‫name: שם המקום.
  • utc_offset הוצא משימוש בספריית המקומות, Maps JavaScript API, השתמשו במקום זאת ב-utc_offset_minutes.
  • utc_offset_minutes מכיל את מספר הדקות של הפרש השעות בין אזור הזמן הנוכחי של המקום הזה לבין שעון UTC. לדוגמה, במקומות בסידני, אוסטרליה, במהלך שעון קיץ, הערך יהיה 660 (‎+11 שעות מ-UTC), ובמקומות בקליפורניה מחוץ לשעון קיץ, הערך יהיה ‎-480 (‎-8 שעות מ-UTC).
  • המאפיין opening_hours מכיל את הפרטים הבאים:
    • open_now (הוצא משימוש בספריית המקומות, Maps JavaScript API; במקום זאת, צריך להשתמש ב- opening_hours.isOpen(). כדי להשתמש ב-isOpen עם פרטי המקום, עיינו בסרטון How to get opening hours in the Places API (Legacy)‎. הערך של open_now הוא ערך בוליאני שמציין אם המקום פתוח כרגע.
    • periods[] הוא מערך של תקופות פתיחה שכולל שבעה ימים, החל מיום ראשון, בסדר כרונולוגי. כל תקופה כוללת:
      • ‫open מכיל זוג אובייקטים של יום ושעה שמתארים מתי המקום נפתח:
        • ‫day מספר מ-0 עד 6, שתואם לימי השבוע, החל מיום ראשון. לדוגמה, הערך 2 מייצג את יום שלישי.
        • ‫time יכול להכיל שעה בפורמט של 24 שעות hhmm (הערכים הם בטווח 0000-2359). הערך של time ידווח לפי אזור הזמן של המקום.
      • ‫close יכול להכיל זוג אובייקטים של יום ושעה שמתארים מתי המקום נסגר. הערה: אם המקום פתוח תמיד, הקטע close לא יופיע בתגובה. אפליקציות יכולות להסתמך על כך ש"פתוח תמיד" מיוצג כתקופת open שמכילה את day עם הערך 0 ואת time עם הערך 0000, וללא close.
    • ‫weekday_text הוא מערך של שבע מחרוזות שמייצגות את שעות הפתיחה בפורמט מסוים לכל יום בשבוע. אם צוין פרמטר language בבקשה של Place Details, שירות 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 מערך של עד חמש ביקורות. כל ביקורת מורכבת מכמה חלקים:
    • ‫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 (אם הוא זמין) או לא תכלול דירוג בכלל.

הפניה למקום באמצעות מזהה מקום

מזהה מקום הוא הפניה ייחודית למקום במפות Google. מזהי מקומות זמינים לרוב המיקומים, כולל עסקים, ציוני דרך, פארקים וצמתים.

כדי להשתמש במזהה מקום באפליקציה, קודם צריך לחפש את המזהה, שזמין ב-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);

תמונות של המקום

אתם יכולים להשתמש בתכונה "תמונת מקום" כדי להוסיף לאתר תוכן צילומי באיכות גבוהה. שירות התמונות מאפשר לכם לגשת למיליוני התמונות שמאוחסנות במסד הנתונים של "מקומות Google" ושל "Google+‎ מקומי". כשמקבלים מידע על מקום באמצעות בקשה ל-Place Details, מזהי התמונות יוחזרו לתוכן הצילום הרלוונטי. גם הבקשות של "חיפוש בסביבה" ו"חיפוש טקסט" מחזירות הפניה לתמונה אחת לכל מקום, אם זה רלוונטי. באמצעות שירות התמונות, תוכלו לגשת לתמונות שהתקבלו ולשנות את הגודל שלהן כך שיתאים לאפליקציה שלכם.

מערך של אובייקטים מסוג PlacePhoto יוחזר כחלק מהאובייקט PlaceResult לכל בקשה מסוג getDetails(),‏ textSearch() או nearbySearch() שבוצעה מול PlacesService.

הערה: מספר התמונות שמוחזרות משתנה בהתאם לבקשה.

  • חיפוש בסביבה או חיפוש טקסט יחזירו לכל היותר אובייקט PlacePhoto אחד.
  • בקשת פרטים תחזיר עד עשרה אובייקטים מסוג PlacePhoto.

כדי לבקש את כתובת ה-URL של התמונה המשויכת, מפעילים את השיטה PlacePhoto.getUrl() ומעבירים אובייקט PhotoOptions תקין. משתמשים באובייקט PhotoOptions כדי לציין את הגובה והרוחב המקסימליים של התמונה. אם מציינים ערך גם ל-maxHeight וגם ל-maxWidth, שירות התמונות ישנה את גודל התמונה לגודל הקטן מבין השניים, תוך שמירה על יחס הגובה-רוחב המקורי.

קטע הקוד הבא מקבל אובייקט של מקום ומוסיף סמן למפה אם יש תמונה. תמונת הסמן שמוגדרת כברירת מחדל מוחלפת בגרסה קטנה של התמונה.

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, אתם צריכים לכלול את הייחוס הנוסף באפליקציה בכל מקום שבו אתם מציגים את התמונה.