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

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

סקירה כללית

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

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

איך מתחילים

אם אינך מתמצא ב-JavaScript JavaScript API או ב-JavaScript, מומלץ לקרוא את JavaScript ואת קבלת מפתח API לפני תחילת העבודה.

הפעלת ממשקי API

לפני ששומרים את הספרייה של מקומות ב-API של JavaScript במפות Google, קודם צריך לוודא שה-API של מקומות Google מופעל במסוף Google Cloud באותו פרויקט שהגדרתם ב-API JavaScript API.

כדי להציג את רשימת ממשקי ה-API המופעלים:

  1. נכנסים למסוף Google Cloud.
  2. לוחצים על הלחצן Select a project, בוחרים את הפרויקט שהגדרתם ב-API של JavaScript JavaScript ולוחצים על Open.
  3. ברשימת ממשקי ה-API במרכז השליטה, מחפשים את Places API.
  4. אם ממשק ה-API של 'מקומות' מופיע ברשימה, הוא כבר מופעל. אם ה-API לא מופיע ברשימה, יש להפעיל אותו:
    1. בחלק העליון של הדף לוחצים על Enable APIs and Services כדי להציג את הכרטיסייה Library. אפשר גם לבחור בתפריט הימני את האפשרות ספרייה.
    2. מחפשים את Places API ובוחרים אותו מרשימת התוצאות.
    3. לוחצים על הפעלה. בסיום התהליך, יופיע הכיתוב Places API ברשימת ממשקי ה-API במרכז הבקרה.

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

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

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

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

הוספת ה-API של מקומות Google לרשימת הגבלות ה-API של מפתח ה-API

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

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

מכסות

הספרייה של מקומות Google, JavaScript API, חולקת מכסת שימוש עם 'ממשק API של מקומות', כפי שמתואר בתיעוד של מגבלות השימוש עבור API API.

מדיניות

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

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

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

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

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

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

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

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

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

בנוסף, עליך להעביר שיטת התקשרות חזרה אל 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);
    }
  });
}
לצפייה בדוגמה

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

'איתור מספר טלפון' מקבל מספר טלפון ומחזיר מקום. כדי להגיש בקשה לאיתור מספר טלפון, צריך לקרוא לשיטה PlacesService findPlaceFromPhoneNumber(), שכוללת את הפרמטרים הבאים:

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

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

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

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

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

יצירת קשר

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

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

חיפושי טקסט מתבצעים באמצעות קריאה לשיטה textSearch() של PlacesService. 

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

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

  • query (חובה) מחרוזת הטקסט שיש לחפש בה, לדוגמה: "מסעדה" או "הרחוב הראשי 123". השם חייב להיות שם של מקום, כתובת או קטגוריה של מוסדות. כל סוג אחר של קלט יכול ליצור שגיאות ולא בטוח שהוא יחזיר תוצאות חוקיות. השירות מקומות Google יחזיר התאמות למועמדים על סמך המחרוזת הזו ויסדר את התוצאות על סמך הרלוונטיות שלהן. הפרמטר הזה הופך אופציונלי אם משתמשים גם בפרמטר type בבקשת החיפוש.
  • אם רוצים:
    • openNow — ערך בוליאני, שמציין ששירות 'מקומות' צריך להחזיר רק את המקומות פתוחים לעסקים בזמן שליחת השאילתה. מקומות שלא יצוינו שעות פתיחה במסד הנתונים של 'מקומות Google', לא יוחזרו אם תכלול את הפרמטר הזה בשאילתה. להגדרה openNow בתור false אין כל השפעה.
    • minPriceLevel ו-maxPriceLevel - הגבלה של תוצאות רק למקומות האלה בטווח המחירים שצוין. הערכים החוקיים הם בטווח של 0 (הכי משתלם) עד 4 (הכי יקר) כולל.
    • אחד מהשניים:
      • bounds — אובייקט google.maps.LatLngBounds שמגדיר את המלבן שבו רוצים לחפש, או
      • location ו-radius — אפשר להטות את התוצאות לעיגול מסוים על ידי העברה של פרמטר location ופרמטר radius. פעולה זו תנחה את השירות מקומות Google להעדיף הצגת תוצאות בתוך אותו מעגל. יכול להיות שעדיין יוצגו תוצאות מחוץ לאזור שהוגדר. המיקום מקבל אובייקט 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 Code 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 האובייקטים שבתגובה מכילים רשימות שיוך (Attribution) זהות.
  • icon מחזירה את כתובת ה-URL עבור סמל PNG צבעוני בגודל 71px x 71px.
  • icon_mask_base_uri מחזיר את כתובת ה-URL הבסיסית עבור סמל שאינו צבוע, עם הסיומת .svg או .png
  • הפונקציה icon_background_color מחזירה את קוד הצבע HEX המוגדר כברירת מחדל בקטגוריית המקום.
  • name: שם המקום.
  • opening_hours עשוי להכיל את המידע הבא:
    • הערך open_now הוא ערך בוליאני שמציין אם המקום פתוח בשעה הזו (הוצא משימוש בספריית 'מקומות', ב-API של JavaScript ב-Maps, ויש להשתמש במקום זאת ב-utc_offset_minutes).
  • place_id הוא מזהה טקסט שמזהה מקום באופן ייחודי. כדי לאחזר מידע על המקום, יש להעביר את המזהה הזה בבקשה להצגת פרטי מקום. למידע נוסף על הפניה למקום עם מזהה מקום.
  • הדירוג של המקום מכיל rating, מ-0.0 עד 5.0, על סמך ביקורות מצטברות של משתמשים.
  • types מערך של סוגים של המקום הזה (למשל, ["political", "locality"] או ["restaurant", "lodging"]). המערך הזה יכול להכיל כמה ערכים או להיות ריק. ייתכן שנכניס ערכים חדשים ללא הודעה מראש. לצפייה ברשימת הסוגים הנתמכים
  • vicinity: כתובת פשוטה של המקום, כולל שם הרחוב, מספר הבית והיישוב, אבל לא המחוז/המדינה, המיקוד או המדינה. לדוגמה, המשרדים הראשיים של Google בסידני, באוסטרליה, מוגדרים לערך 5/48 Pirrama Road, Pyrmont של vicinity.

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

כברירת מחדל, כל חיפוש מקום מחזיר עד 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;
index.ts

JavaScript

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

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

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

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

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

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

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

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

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

window.initMap = initMap;
index.js
דוגמה

לדגום

פרטי מקומות

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

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

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

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

Basic

הקטגוריה 'בסיסי' כוללת את השדות הבאים:
address_component, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color,name, permanently_closed (הוצאה משימוש), photo, place_id, plus_code, type, url, utc_offset (במקומות אחרים, ב-Google{/2,

יצירת קשר

קטגוריית אנשי הקשר כוללת את השדות הבאים:
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 המיקום המצוין לא נמצא במסד הנתונים של מקומות Google.
  • REQUEST_DENIED: לדף האינטרנט אסור להשתמש ב- PlacesService.
  • UNKNOWN_ERROR: לא ניתן לעבד את בקשת PlacesService עקב שגיאת שרת. הבקשה עשויה להצליח אם תנסו שוב.
  • ZERO_RESULTS: לא נמצאה תוצאה לבקשה הזו.

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

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

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

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

    • types[] הוא מערך שמציין את הסוג של רכיב הכתובת. לצפייה ברשימת הסוגים הנתמכים
    • long_name הוא התיאור המלא של הטקסט או השם של רכיב הכתובת שמוחזר על ידי Geocoder.
    • short_name הוא שם טקסט מקוצר עבור הרכיב של הכתובת, אם הוא זמין. לדוגמה, רכיב כתובת במדינה באלסקה עשוי לכלול long_name של "Alaska" ו- 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 Code 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 של סוכנות הרכב בסידני שבאוסטרליה הוא +61 2 9374 4000.
  • name: שם המקום.
  • utc_offset הוצא משימוש בספריית 'מקומות', ב-API של JavaScript, השתמש ב-utc_offset_minutes במקום זאת.
  • הערך utc_offset_minutes מכיל את מספר הדקות שבאזור הזמן הנוכחי של המקום הזה מתקזז מ-UTC. לדוגמה, במקומות בסידני, אוסטרליה – שעון קיץ 660 (+11 שעות UTC) ובמקומות בקליפורניה מחוץ לשעון קיץ
  • opening_hours מכיל את המידע הבא:
    • open_now (הוצא משימוש בספריית 'מקומות', ב-API של JavaScript במפות Google; במקום זאת, יש להשתמש opening_hours.isOpen(). בסרטון הזה מוסבר איך להשתמש ב-isOpen עם פרטי המקום.) ערך בוליאני שמציין אם המקום פתוח בשעה הנוכחית.
    • periods[] הוא מערך של תקופות פתיחה המכסות שבעה ימים, החל מיום ראשון, בסדר כרונולוגי. כל תקופה כוללת:
      • השדה open מכיל צמד אובייקטים של יום ושעה, שמתארים מתי המקום נפתח:
        • day מספר בין 0 ל-6, בהתאמה לימים בשבוע, החל מיום ראשון. לדוגמה, 2 פירושו יום שלישי.
        • time עשוי להכיל שעה ביום בפורמט של 24 שעות (hhm). הערכים (בטווח 0000-2359). ה-time ידווחו באזור הזמן של המקום.
      • close עשוי להכיל זוג אובייקטים של יום ושעה שמתארים את סגירת המקום. הערה: אם מקום כלשהו פתוח כל הזמן, התשובה שבקטע close תהיה חסרה. אפליקציות יכולות להסתמך על כך שתמיד יש ייצוג כתקופה של open שמכילה את day עם הערך 0 ואת time עם הערך 0000, ללא close.
    • הערך weekday_text הוא מערך של 7 מחרוזות שמייצגות את שעות הפתיחה בפורמט המתאים לכל יום בשבוע. אם הפרמטר language צוין בבקשה 'פרטי מקום', לשירות 'מקומות' יש להזין את שעות הפתיחה בפורמט המתאים לשפה הזו. הסדר של הרכיבים במערך הזה תלוי בפרמטר 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 מקומות', ביקורות טקסט נחשבות כאופציונליות; לפיכך, שדה זה עשוי להיות ריק.
  • types מערך של סוגים של המקום הזה (למשל, ["political", "locality"] או ["restaurant", "lodging"]). המערך הזה יכול להכיל כמה ערכים או להיות ריק. ייתכן שנכניס ערכים חדשים ללא הודעה מראש. לצפייה ברשימת הסוגים הנתמכים
  • url: כתובת URL של דף Google הרשמי של המקום הזה. זהו הדף בבעלות Google שמכיל את המידע הזמין ביותר על המקום. האפליקציות צריכות לקשר לדף הזה או להטמיע אותו בכל מסך שמוצגות בו תוצאות מפורטות על המקום.
  • vicinity: כתובת פשוטה של המקום, כולל שם הרחוב, מספר הבית והיישוב, אבל לא המחוז/המדינה, המיקוד או המדינה. לדוגמה, המשרדים הראשיים של Google בסידני, באוסטרליה, מוגדרים לערך 5/48 Pirrama Road, Pyrmont של vicinity. הנכס vicinity מוחזר רק עבור חיפוש בקרבת מקום.
  • באתר של website מופיע האתר המורשה, כמו דף הבית של עסק.

הערה: דירוגים רב-ממדיים לא יהיו זמינים בכל המיקומים. אם יתקבלו מעט מדי ביקורות, דירוג הפרטים יכלול דירוג קודם על סולם מ-0.0 עד 5.0 (אם הוא זמין), או ללא דירוג בכלל.

הפניה למקום עם מזהה מקום

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

כדי להשתמש במזהה מקום באפליקציה, קודם צריך לחפש את המזהה. המזהה הזה זמין ב-PlaceResult מתוך הבקשה לחיפוש מקומות או לפרטים. לאחר מכן אפשר להשתמש במזהה המקום הזה כדי לחפש את פרטי המקום.

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

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

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