‫ Places UI Kit: ספרייה מוכנה לשימוש שמאפשרת למפתחים להתאים אישית ולשלוט. כדאי לנסות ולשתף את המשוב שלך על חוויית השימוש בערכת ממשק המשתמש.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

סקירה כללית

הפונקציות בספריית המקומות, 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 (Legacy) לרשימת ההגבלות על ממשקי API של מפתח ה-API

החלת הגבלות על מפתחות API מגבילה את השימוש במפתח ה-API לממשק API אחד או יותר או לערכת SDK אחת או יותר. המערכת תעבד בקשות ל-API או ל-SDK שמשויכים למפתח ה-API. בקשות ל-API או ל-SDK שלא משויכים למפתח ה-API ייכשלו. כדי להגביל את השימוש במפתח API בספריית המקומות, Maps JavaScript API:

נכנסים למסוף Google Cloud.
לוחצים על התפריט הנפתח של הפרויקט ובוחרים את הפרויקט שמכיל את מפתח ה-API שרוצים לאבטח.
לוחצים על לחצן התפריט ובוחרים באפשרות Google Maps Platform > Credentials (פלטפורמת מפות Google > פרטי כניסה).
בדף Credentials, לוחצים על השם של מפתח ה-API שרוצים לאבטח.
בדף Restrict and rename API key, מגדירים את ההגבלות:
- הגבלות על ממשקי API
לוחצים על שמירה.

מכסות שימוש ומדיניות

מכסות

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

מדיניות

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

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

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

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

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

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

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

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

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

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

‫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 מקבלת מספר טלפון ומחזירה מקום. כדי לשלוח בקשה לחיפוש מקום לפי מספר טלפון, קוראים לשיטה PlacesServicefindPlaceFromPhoneNumber() של, שמקבלת את הפרמטרים הבאים:

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

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

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

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

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

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

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. שימו לב: החל מגרסה 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 ‏PlacesServicetextSearch().

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

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

‫query (חובה) מחרוזת הטקסט שרוצים לחפש, לדוגמה: 'מסעדה' או 'רחוב ראשי 123'. הערך הזה צריך להיות שם של מקום, כתובת או קטגוריה של בתי עסק. סוגים אחרים של קלט עלולים ליצור שגיאות, ואין ערובה לכך שהם יחזירו תוצאות תקינות. שירות Places יחזיר התאמות אפשריות על סמך המחרוזת הזו, ויסדר את התוצאות לפי מידת הרלוונטיות שלהן. הפרמטר הזה הופך לאופציונלי אם משתמשים גם בפרמטר type בבקשת החיפוש.
אופציונלי:
- ‫openNow – ערך בוליאני שמציין ששירות Places צריך להחזיר רק את המקומות שפתוחים לעסקים בזמן שליחת השאילתה. אם לא צוינו שעות פתיחה במקומות מסוימים במסד הנתונים של Google Places, המקומות האלה לא יוחזרו אם תכללו את הפרמטר הזה בשאילתה. ההגדרה openNow לערך false לא משפיעה.
- ‫minPriceLevel ו-maxPriceLevel — מגבילים את התוצאות למקומות שנמצאים ברמת המחיר שצוינה. הערכים התקפים הם בטווח שבין 0 (הכי משתלם) ל-4 (הכי יקר), כולל.
- אחת מהאפשרויות:
  - ‫bounds, שחייב להיות אובייקט google.maps.LatLngBounds שמגדיר את אזור החיפוש המלבני. המרחק האלכסוני המקסימלי שנתמך לאזור הגבולות הוא בערך 100,000 מטרים.
  - ‫location ו-radius – אפשר להטות את התוצאות לעיגול מסוים על ידי העברת הפרמטרים location ו-radius. הפעולה הזו תגרום לשירות המקומות להציג תוצאות בתוך העיגול הזה. יכול להיות שעדיין יוצגו תוצאות מחוץ לאזור שהוגדר. המיקום מקבל אובייקט 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 מ' בקו המשווה) או קטן יותר. אפשר להשתמש ב-OLC במקום בכתובות במקומות שבהם אין כתובות (במקומות שבהם הבניינים לא ממוספרים או שהרחובות לא נקראים בשם).
ה-Plus Code מורכב מקוד גלובלי ומקוד משולב:
- ‫global_code הוא קוד אזור בן 4 תווים וקוד מקומי בן 6 תווים או יותר (849VCWC8+R9).
- ‫compound_code הוא קוד מקומי בן 6 תווים או יותר עם מיקום מפורש (CWC8+R9, Mountain View, CA, USA). אל תנתחו את התוכן הזה באופן אוטומטי.
בדרך כלל, גם הקוד הגלובלי וגם הקוד המורכב מוחזרים. עם זאת, אם התוצאה היא במיקום מרוחק (למשל, באוקיינוס או במדבר), יכול להיות שיוחזר רק הקוד הגלובלי.
‫html_attributions: מערך של שיוכים שצריך להציג כשמציגים את תוצאות החיפוש. כל רשומה במערך מכילה את הטקסט ב-HTML של ייחוס אחד. הערה: זהו צבירה של כל השיוכים של כל התשובה לחיפוש. לכן, כל האובייקטים מסוג PlaceResult בתשובה מכילים רשימות שיוך זהות.
‫icon מחזירה את כתובת ה-URL של סמל PNG צבעוני בגודל ‎71px x 71px.
‫icon_mask_base_uri מחזירה את כתובת ה-URL הבסיסית של סמל לא צבעוני, ללא הסיומת ‎ .svg או ‎ .png.
‫icon_background_color מחזירה את קוד הצבע ההקסדצימלי שמוגדר כברירת מחדל לקטגוריה של המקום.
‫name: שם המקום.
opening_hours עשוי להכיל את הפרטים הבאים:
- ‫open_now הוא ערך בוליאני שמציין אם המקום פתוח בשעה הנוכחית (הוצא משימוש בספריית המקומות, Maps JavaScript API, צריך להשתמש במקומו ב-utc_offset_minutes).
‫place_id הוא מזהה טקסטואלי שמזהה באופן ייחודי מקום. כדי לאחזר מידע על המקום, מעבירים את המזהה הזה בבקשה לפרטי מקום. איך מציינים מקום באמצעות מזהה מקום
‫rating מכיל את דירוג המקום, מ-0.0 עד 5.0, על סמך ביקורות מצטברות של משתמשים.
types מערך של סוגים של המקום הזה (למשל, ["political", "locality"] או ["restaurant", "lodging"]). המערך הזה יכול להכיל כמה ערכים או להיות ריק. יכול להיות שיוצגו ערכים חדשים ללא הודעה מוקדמת. לרשימת הסוגים הנתמכים
‫vicinity: כתובת פשוטה של המקום, כולל שם הרחוב, המספר ברחוב והיישוב, אבל לא המחוז/המדינה, המיקוד או המדינה. לדוגמה, למשרד של Google בסידני, אוסטרליה, יש ערך vicinity של 5/48 Pirrama Road, Pyrmont.

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

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

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

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

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

TypeScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

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

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

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

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;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

לדוגמה

פרטי מקומות

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

Place Details Requests

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

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

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

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

לדוגמה

אפשר לבקש את place_id של מקום מסוים, ללא תשלום. כדי לעשות את זה, מתקשרים אל getDetails() ומציינים רק את השדה place_id.

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

הפרמטר fields מקבל מערך של מחרוזות (שמות שדות).

משתמשים בפרמטר 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

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

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

Place Details Responses

קודי סטטוס

אובייקט התגובה 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 Alaska ואת הערך short_name AK (קיצור של 2 אותיות לשימוש בדואר).
חשוב לזכור את העובדות הבאות לגבי המערך address_components[]:
- מערך רכיבי הכתובת יכול להכיל יותר רכיבים מהערך formatted_address.
- המערך לא בהכרח כולל את כל הישויות הפוליטיות שמכילות כתובת, מלבד אלה שכלולות ב-formatted_address. כדי לאחזר את כל הישויות הפוליטיות שמכילות כתובת ספציפית, צריך להשתמש בהמרת קואורדינטות לכתובות (reverse geocoding) ולהעביר את קו הרוחב/קו האורך של הכתובת כפרמטר לבקשה.
- אין ערובה לכך שפורמט התשובה יישאר זהה בין בקשות שונות. בפרט, מספר ה-address_components משתנה בהתאם לכתובת המבוקשת, ויכול להשתנות לאורך זמן עבור אותה כתובת. מיקום הרכיב במערך יכול להשתנות. אפשר לשנות את סוג הרכיב. יכול להיות שרכיב מסוים לא יופיע בתגובה מאוחרת יותר.
הסמל business_status מציין את סטטוס הפעילות של המקום, אם מדובר בעסק. המאפיין יכול להכיל אחד מהערכים הבאים:
- OPERATIONAL
- CLOSED_TEMPORARILY
- CLOSED_PERMANENTLY
אם לא קיימים נתונים, לא מוחזר business_status.
‫formatted_address: כתובת המקום שקריאה לאנשים.
לרוב הכתובת הזו זהה לכתובת למשלוח דואר. שימו לב שבמדינות מסוימות, כמו בריטניה, אסור להפיץ כתובות דואר אמיתיות בגלל הגבלות רישוי.

הכתובת המעוצבת מורכבת באופן לוגי מרכיב כתובת אחד או יותר. לדוגמה, הכתובת '111 8th Avenue, New York, NY' מורכבת מהרכיבים הבאים: '111' (מספר הבית), '8th Avenue' (המסלול), 'New York' (העיר) ו-'NY' (המדינה בארה"ב).

אל תנתחו את הכתובת המעוצבת באופן פרוגרמטי. במקום זאת, צריך להשתמש ברכיבי הכתובת הנפרדים, שהתשובה של ה-API כוללת בנוסף לשדה הכתובת המעוצב.
‫formatted_phone_number: מספר הטלפון של המקום, בפורמט שמותאם ל הסכם האזורי לגבי המספר.
‫geometry: מידע שקשור לגיאומטריה של המקום. זה כולל:
- ‫location מספק את קו הרוחב וקו האורך של המקום.
- ‫viewport מגדיר את אזור התצוגה המועדף במפה כשמציגים את המקום הזה.
‫permanently_closed (הוצא משימוש) הוא ערך בוליאני שמציין אם המקום נסגר באופן קבוע או זמני (הערך הוא true). אין להשתמש ב-permanently_closed. במקום זאת, אפשר להשתמש בשיטה business_status כדי לקבל את סטטוס הפעילות של עסקים.
‫plus_code (ראו Open Location Code וPlus Codes) הוא הפניה מקודדת למיקום, שנגזרת מקואורדינטות של קו רוחב וקו אורך, שמייצגת אזור: 1/8000 של מעלה על 1/8000 של מעלה (כ-14 מ' על 14 מ' בקו המשווה) או קטן יותר. אפשר להשתמש ב-OLC במקום בכתובות במקומות שבהם אין כתובות (במקומות שבהם הבניינים לא ממוספרים או שהרחובות לא נקראים בשם).
ה-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 הוצא משימוש בספריית המקומות, Maps JavaScript API, צריך להשתמש ב-utc_offset_minutes במקום זאת.
‫utc_offset_minutes מכיל את מספר הדקות שבהן אזור הזמן הנוכחי של המקום הזה שונה משעון UTC. לדוגמה, במקומות בסידני שבאוסטרליה במהלך שעון הקיץ, הערך יהיה 660 (שעה אחת לפני UTC), ובמקומות בקליפורניה מחוץ לשעון הקיץ, הערך יהיה ‎-480 (שמונה שעות אחרי UTC).
opening_hours כולל את הפרטים הבאים:
- open_now (הוצא משימוש בספריית המקומות, Maps JavaScript API; במקומו צריך להשתמש ב-opening_hours.isOpen()). הסרטון איך מקבלים את שעות הפתיחה ב-Places API (מדור ישן) מסביר איך להשתמש ב-isOpen עם פרטי מקום .) ‫`open_now` הוא ערך בוליאני שמציין אם המקום פתוח בזמן הנוכחי.
- ‫periods[] הוא מערך של תקופות פתיחה שכולל שבעה ימים, החל מיום ראשון, בסדר כרונולוגי. כל תקופה כוללת:
  - ‫open מכיל זוג של אובייקטים של יום ושעה שמתארים את שעת הפתיחה של המקום:
    - ‫day מספר מ-0 עד 6, שמתאים לימי השבוע, החל מיום ראשון. לדוגמה, הערך 2 מייצג את יום שלישי.
    - time יכול להכיל שעה בפורמט של 24 שעות hhmm (הערכים הם בטווח 0000 עד 2359). ‫ time ידווח לפי אזור הזמן של המקום.
  - ‫close עשוי להכיל זוג של אובייקטים של יום ושעה שמתארים מתי המקום נסגר. הערה: אם המקום פתוח תמיד, הקטע close לא יופיע בתגובה. אפליקציות יכולות להסתמך על כך ששעות הפתיחה הן תמיד שמוצגות כפרק זמן open שמכיל את הערך 0 ב-day ואת הערך 0000 ב-time, ושאין 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 הדירוג הכולל של המשתמש למקום הזה. This is a whole number, ranging from 1 to 5.
- text הביקורת של המשתמש. כשבודקים מיקום באמצעות Google Places, ביקורות טקסט נחשבות לאופציונליות, ולכן השדה הזה עשוי להיות ריק.
types מערך של סוגים של המקום הזה (למשל, ["political", "locality"] או ["restaurant", "lodging"]). המערך הזה יכול להכיל כמה ערכים או להיות ריק. יכול להיות שיוצגו ערכים חדשים ללא הודעה מוקדמת. לרשימת הסוגים הנתמכים
‫url: כתובת ה-URL של הדף הרשמי של Google למקום הזה. זהו דף בבעלות Google שמכיל את המידע הטוב ביותר שזמין על המקום. באפליקציות צריך לקשר לדף הזה או להטמיע אותו בכל מסך שבו מוצגות למשתמש תוצאות מפורטות לגבי המקום.
‫vicinity: כתובת פשוטה של המקום, כולל שם הרחוב, המספר ברחוב והיישוב, אבל לא המחוז/המדינה, המיקוד או המדינה. לדוגמה, למשרד של Google בסידני, אוסטרליה, יש ערך vicinity של 5/48 Pirrama Road, Pyrmont. המאפיין vicinity מוחזר רק עבור חיפוש בסביבה.
‫website מופיע האתר הרשמי של המקום הזה, למשל דף הבית של העסק.

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

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

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

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

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

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

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

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

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

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

ספריית מקומות קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

סקירה כללית

תחילת העבודה

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

הוספת Places API (Legacy) לרשימת ההגבלות על ממשקי API של מפתח ה-API

מכסות שימוש ומדיניות

מכסות

מדיניות

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

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

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

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

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

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

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

בקשות לחיפוש טקסט

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

קודי סטטוס

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

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

TypeScript

JavaScript

פרטי מקומות

Place Details Requests

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

Place Details Responses

קודי סטטוס

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

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

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

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