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

סקירה כללית

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

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

תחילת העבודה

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

הפעלת ממשקי API

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

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

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

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

מכסות

לספריית Places יש מכסת שימוש משותפת עם Places API, כפי שמתואר במסמך 'מגבלות שימוש' של Places API.

מדיניות

השימוש ב-Places Library, ‏ Maps JavaScript API חייב להתבצע בהתאם למדיניות שמפורטת לגבי Places API.

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

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

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

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

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

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

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

  • query (חובה) מחרוזת הטקסט שרוצים לחפש. לדוגמה: 'restaurant' או '123 Main Street'. השם צריך להיות שם של מקום, כתובת או קטגוריה של מוסדות. כל סוגי הקלט האחרים עלולים לגרום לשגיאות, ולא בטוח שהם יחזירו תוצאות תקינות. Places API יחזיר התאמות לפי המחרוזת הזו ויסדר את התוצאות לפי הרלוונטיות המשוערת שלהן.
  • 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);
    }
  });
}
 להצגת דוגמה

איתור מקום לפי מספר טלפון

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

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

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

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

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

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

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

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

ניסיון של דוגמה

פרטי מקומות

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

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

כדי לבקש פרטי מקום, צריך לבצע קריאה ל-method‏ 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.

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

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

תוצאות של Place Details

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

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

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

    • types[] הוא מערך שמציין את הסוג של רכיב הכתובת. כאן אפשר לעיין ברשימת הסוגים הנתמכים.
    • long_name הוא התיאור המלא בטקסט או השם של רכיב הכתובת, כפי שהוחזר על ידי המקודד הגיאוגרפי.
    • short_name הוא שם מקוצר של רכיב הכתובת, אם הוא זמין. לדוגמה, רכיב כתובת של המדינה אלסקה יכול לכלול את הערך long_name של 'אלסקה' ואת הערך short_name של 'AK', לפי הקיצור הדו-אותיות של המדינה.

    שימו לב לעובדות הבאות לגבי המערך 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 מכיל את מספר הטלפון של המקום בפורמט בינלאומי. הפורמט הבינלאומי כולל את קוד המדינה, ומתחיל בסימן הפלוס (+). לדוגמה, הערך של 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 עם פרטי המקום). הוא ערך בוליאני שמציין אם המקום פתוח בשעה הנוכחית.
    • periods[] הוא מערך של תקופות פתיחה שמכסות שבעה ימים, החל מיום ראשון, בסדר כרונולוגי. כל תקופה מכילה:
      • השדה open מכיל זוג אובייקטים של יום ושעה שמתארים את שעת הפתיחה של המקום:
        • day מספר מ-0 עד 6, שתואם לימים השבוע, החל מיום ראשון. לדוגמה, 2 פירושו יום שלישי.
        • השדה time יכול להכיל שעה בפורמט 24 שעות (hh:mm) (הערכים נעים בטווח 0000 עד 2359). הערך של time ידווח לפי אזור הזמן של המקום.
      • השדה close עשוי להכיל זוג אובייקטים של יום ושעה שמתארים את השעה שבה המקום נסגר. הערה: אם המקום פתוח תמיד, הקטע close לא יופיע בתגובה. אפליקציות יכולות להסתמך על כך שחלון תמיד פתוח יהיה מיוצג כתקופה open שמכילה את הערך 0 ב-day ואת הערך 0000 ב-time, ללא close.
    • weekday_text הוא מערך של שבע מחרוזות שמייצגות את שעות הפתיחה בפורמט המתאים לכל יום בשבוע. אם הוגדר פרמטר 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 Places, ביקורות טקסט נחשבות אופציונליות, ולכן יכול להיות שהשדה הזה יהיה ריק.
  • types מערך של סוגי המקום (למשל, ["political", "locality"] או ["restaurant", "lodging"]). המערך הזה יכול להכיל כמה ערכים, או להיות ריק. ייתכן שנוסיף ערכים חדשים ללא הודעה מוקדמת. כאן אפשר לעיין ברשימת הסוגים הנתמכים.
  • url: כתובת ה-URL של הדף הרשמי של Google לגבי המקום הזה. זהו הדף שבבעלות Google שמכיל את המידע הטוב ביותר שזמין על המקום. האפליקציות חייבות לקשר לדף הזה או להטמיע אותו בכל מסך שבו מוצגות למשתמש תוצאות מפורטות לגבי המקום.
  • vicinity: כתובת פשוטה של המקום, כולל שם הרחוב, מספר הבית והיישוב, אבל לא את המחוז, המיקוד או המדינה. לדוגמה, הערך של השדה vicinity במשרד של Google בסידני, אוסטרליה הוא 5/48 Pirrama Road, Pyrmont. הנכס 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. כשמקבלים מידע על מקום באמצעות בקשה לפרטים על מקום, המערכת מחזירה הפניות לתמונות של תוכן צילום רלוונטי. הבקשות לחיפוש בקרבת מקום ולחיפוש לפי טקסט מחזירות גם הן הפניה לתמונה אחת לכל מקום, במקרים הרלוונטיים. לאחר מכן תוכלו להשתמש בשירות Photos כדי לגשת לתמונות שצוינו ולשנות את גודל התמונה לגודל האופטימלי לאפליקציה.

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