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

סקירה כללית

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

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

תחילת העבודה

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

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

שירות המקומות הוא ספרייה עצמאית, נפרדת מהקוד הראשי של 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

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

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

מכסות

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

מדיניות

השימוש בספריית המקומות, Maps JavaScript API, חייב להיות בהתאם למדיניות שמתוארת במאמר בנושא Places API.

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

בעזרת שירות המקומות אפשר לבצע חיפושים מהסוגים הבאים:

• ‫Find Place from Query מחזירה מקום על סמך שאילתת טקסט (לדוגמה, השם או הכתובת של מקום).
• ‫Find Place from Phone Number מחזירה מקום על סמך מספר טלפון.
• ‫חיפוש בקרבת מקום מחזירה רשימה של מקומות בסביבה על סמך המיקום של המשתמש.
• ‫חיפוש טקסט מחזירה רשימה של מקומות בסביבה על סמך מחרוזת חיפוש, למשל: ‫"Pizza".
• בקשות לפרטי מקום מחזירות מידע מפורט יותר על מקום ספציפי, כולל ביקורות של משתמשים.

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

חיפוש בקשות לחיפוש מקום

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

• ‫חיפוש מקום מתוך שאילתה
• ‫חיפוש מקום ממספר טלפון

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

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

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

צריך גם להעביר שיטת קריאה חוזרת ל-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);
    }
  });
}

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

הפונקציה Find Place from Phone Number מקבלת מספר טלפון ומחזירה מקום. כדי לשלוח בקשה לחיפוש מקום לפי מספר טלפון, קוראים לשיטה PlacesService של findPlaceFromPhoneNumber(), שמקבלת את הפרמטרים הבאים:

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

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

שדות (שיטות חיפוש מקום)

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

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

יצירת קשר

אטמוספרה

השיטות 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. הערה: החל מגרסה 3.9, השיטה nearbySearch() מחליפה את השיטה search().

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 (אופציונלי) — ערך בוליאני, שמציין ששירות המקומות צריך להחזיר רק את המקומות שפתוחים לעסקים בזמן שליחת השאילתה. אם לא צוינו שעות פתיחה במקומות במסד הנתונים של Google Places, הם לא יוחזרו אם תכללו את הפרמטר הזה בשאילתה. הגדרה של openNow לערך false לא משפיעה.
• ‫rankBy (אופציונלי) – מציין את הסדר שבו התוצאות מוצגות. הערכים האפשריים:
  • ‫google.maps.places.RankBy.PROMINENCE (ברירת מחדל). האפשרות הזו ממיינת את התוצאות לפי החשיבות שלהן. הדירוג ייתן עדיפות למקומות בולטים ברדיוס שהוגדר על פני מקומות סמוכים שתואמים אבל פחות בולטים. החשיבות של מקום יכולה להיות מושפעת מהדירוג שלו באינדקס של Google, מהפופולריות שלו בעולם וגורמים אחרים. אם מציינים את הפרמטר google.maps.places.RankBy.PROMINENCE, חובה לציין גם את הפרמטר radius.
  • ‫google.maps.places.RankBy.DISTANCE. האפשרות הזו ממיינת את התוצאות בסדר עולה לפי המרחק שלהן מהמיקום שצוין location (חובה). שימו לב: אם מציינים RankBy.DISTANCE, אי אפשר לציין bounds או radius בהתאמה אישית. כשמציינים את RankBy.DISTANCE, צריך לציין גם את keyword, name או type.
• ‫type — הגבלת התוצאות למקומות שתואמים לסוג שצוין. אפשר לציין רק סוג אחד (אם מציינים יותר מסוג אחד, המערכת מתעלמת מכל הסוגים אחרי הערך הראשון). לרשימת הסוגים הנתמכים

צריך גם להעביר שיטת קריאה חוזרת ל-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'. הערך צריך להיות שם של מקום, כתובת או קטגוריה של בתי עסק. סוגי קלט אחרים עלולים ליצור שגיאות, ואין ערובה לכך שיוחזרו תוצאות תקינות. שירות המקומות יחזיר התאמות אפשריות על סמך המחרוזת הזו, ויסדר את התוצאות לפי מידת הרלוונטיות שלהן. הפרמטר הזה הופך לאופציונלי אם משתמשים גם בפרמטר type בבקשת החיפוש.
• אופציונלי:
  • ‫openNow – ערך בוליאני שמציין ששירות המקומות צריך להחזיר רק את המקומות שפתוחים לעסקים בזמן שליחת השאילתה. אם לא צוינו שעות פתיחה במקומות מסוימים במסד הנתונים של Google Places, המקומות האלה לא יוחזרו אם תכללו את הפרמטר הזה בשאילתה. הגדרה של openNow לערך false לא משפיעה על כלום.
  • ‫minPriceLevel ו-maxPriceLevel — הגבלת התוצאות למקומות שנמצאים ברמת המחיר שצוינה. הערכים החוקיים הם בטווח שבין 0 (המחיר הכי משתלם) ל-4 (המחיר הכי גבוה), כולל.
  • אחת מהאפשרויות הבאות:
    • ‫bounds, שחייב להיות אובייקט google.maps.LatLngBounds שמגדיר את אזור החיפוש המלבני. המרחק האלכסוני המקסימלי שנתמך לאזור הגבולות הוא בערך 100,000 מטרים.
    • ‫location ו-radius – אפשר להטות את התוצאות לעיגול מסוים על ידי העברת הפרמטרים location ו-radius. הפעולה הזו תגרום לשירות המקומות להציג תוצאות בתוך העיגול הזה. יכול להיות שיוצגו תוצאות מחוץ לאזור שהוגדר. המיקום מקבל אובייקט google.maps.LatLng, והרדיוס מקבל מספר שלם פשוט שמייצג את רדיוס העיגול במטרים. הרדיוס המקסימלי המותר הוא 50,000 מטרים.
  • ‫type — הגבלת התוצאות למקומות שתואמים לסוג שצוין. אפשר לציין רק סוג אחד (אם מציינים יותר מסוג אחד, המערכת מתעלמת מכל הסוגים אחרי הרשומה הראשונה). כאן אפשר לעיין ברשימת הסוגים הנתמכים.

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

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

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

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

כדי לראות את קבוצת התוצאות הבאה, צריך להתקשר אל nextPage. כל דף תוצאות צריך להיות מוצג לפני הצגת דף התוצאות הבא. שימו לב: כל חיפוש נספר כבקשה אחת במסגרת מגבלות השימוש.

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

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

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

פרטי מקומות

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

בקשות לפרטי מקום

פרטי המקום מתקבלים באמצעות קריאה לשיטה getDetails() של השירות.

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

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

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

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

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

אטמוספרה

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

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

תשובות לשאלות על מקומות

קודי סטטוס

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

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

תוצאות של פרטי מקום

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

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

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

  • ‫types[] הוא מערך שמציין את הסוג של רכיב הכתובת. יכול להיות שרכיב הכתובת יכיל מערך ריק של סוגים אם אין סוגים ידועים לרכיב הכתובת הזה. יכול להיות ש-API יוסיף ערכים חדשים של סוגים לפי הצורך. מידע נוסף זמין במאמר סוגי כתובות וסוגי רכיבי כתובות.
  • ‫long_name הוא תיאור הטקסט המלא או השם של רכיב הכתובת שמוחזר על ידי הגיאוקודר.
  • ‫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: כתובת המקום שקריאה לאנשים.

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

  הכתובת המעוצבת מורכבת באופן לוגי מרכיבי כתובת אחד או יותר. לדוגמה, הכתובת "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 מכיל את מספר הטלפון של המקום בפורמט לחיוג בינלאומי. פורמט לחיוג בינלאומי כולל את קוד המדינה, ומתחיל בסימן הפלוס (+). לדוגמה, קוד המדינה של משרד Google בסידני, אוסטרליה, הוא +61 2 9374 4000.international_phone_number
• ‫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 עם Place Details מפורטות בסרטון איך מקבלים את שעות הפתיחה ב-Places API). ‫`open_now` הוא ערך בוליאני שמציין אם המקום פתוח בזמן הנוכחי.
  • ‫periods[] הוא מערך של תקופות פתיחה שכולל שבעה ימים, החל מיום ראשון, בסדר כרונולוגי. כל תקופה כוללת:
    • ‫open מכיל זוג של אובייקטים של יום ושעה שמתארים את שעת הפתיחה של המקום:
      • ‫day מספר מ-0 עד 6, שמתאים לימי השבוע, החל מיום ראשון. לדוגמה, 2 מייצג את יום שלישי.
      • time יכול להכיל שעה ביום בפורמט hhmm של 24 שעות (הערכים הם בטווח 0000 עד 2359). הערך של time ידווח לפי אזור הזמן של המקום.
    • ‫close עשוי להכיל זוג של אובייקטים של יום ושעה שמתארים מתי המקום נסגר. הערה: אם מקום פתוח תמיד, הקטע close לא יופיע בתגובה. אפליקציות יכולות להסתמך על כך ששעות הפתיחה 'תמיד פתוח' ייוצגו תמיד כפרק זמן open שמכיל את הערך day עם הערך 0 ואת הערך time עם הערך 0000, ולא יכיל את הערך close.
  • ‫weekday_text הוא מערך של שבע מחרוזות שמייצגות את שעות הפתיחה המעוצבות לכל יום בשבוע. אם צוין פרמטר language בבקשה של Place Details, שירות המקומות יתאים את הפורמט של שעות הפתיחה ויבצע התאמה לשוק המקומי שלהן בהתאם לשפה. הסדר של הרכיבים במערך הזה תלוי בפרמטר 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: כתובת פשוטה של המקום, כולל שם הרחוב, מספר הבית והרשות המוניציפאלית, אבל לא המחוז/מדינה (State), המיקוד או המדינה. לדוגמה, למשרד של 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+ Local. כשמקבלים מידע על מקום באמצעות בקשה ל-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, צריך לכלול את השיוך הנוסף באפליקציה בכל מקום שבו התמונה מוצגת.