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

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

הערה: מעכשיו מתבצעת אכיפה של הגבלות על מפתחות API

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

הערה: ספריות בצד השרת

בדף הזה מתואר השירות בצד הלקוח שזמין עם Maps JavaScript API. אם רוצים לעבוד עם שירותי האינטרנט של מפות Google בשרת, כדאי לעיין בלקוח Node.js לשירותי מפות Google. בדף שבקישור הזה מוצגים גם לקוח Java, לקוח Python ו-Go Client עבור שירותי מפות Google.

סקירה כללית

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

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

איך מתחילים

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

הפעלת ממשקי API

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

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

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

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

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

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

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

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

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

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

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

מכסות

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

כללי מדיניות

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

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

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

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

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

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

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

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

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

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

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

כמו כן, צריך להעביר ל-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);
    }
  });
}

להצגת דוגמה

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

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

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

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

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

השדות opening_hours.open_now ו-utc_offset ב-'SDK של מקומות' ל-iOS הוצאו משימוש ב-20 בנובמבר 2019, והם יושבתו ב-20 בפברואר 2021. מידע נוסף

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

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

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

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

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

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

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

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

• query (חובה) מחרוזת הטקסט שבה רוצים לחפש, לדוגמה: "מסעדה" או "123 רחוב ראשי". השם חייב להיות שם, כתובת או קטגוריה של מקומות. כל סוג אחר של קלט יכול ליצור שגיאות ולא בטוח שהוא יחזיר תוצאות חוקיות. השירות מקומות יחזיר התאמות למועמדים על סמך המחרוזת הזו ויסדר את התוצאות על סמך הרלוונטיות שלהן. הפרמטר הזה הוא אופציונלי אם משתמשים בפרמטר type גם בבקשת החיפוש.
• אם רוצים:
  • openNow — ערך בוליאני שמציין שהשירות 'מקומות' צריך להחזיר רק את המקומות פתוחים לעסקים בזמן שליחת השאילתה. מקומות שלא יצוינו בהם שעות הפתיחה במסד הנתונים של מקומות Google לא יוחזרו אם כוללים את הפרמטר הזה בשאילתה. המדיניות openNow קובעת את false.
  • minPriceLevel ו-maxPriceLevel — מגבילות את התוצאות רק למקומות האלה בטווח המחירים שצוין. הערכים החוקיים נעים בין 0 (הזול ביותר) ל-4 (היקר ביותר), כולל.
  • אחד מהשניים:
    • bounds — אובייקט google.maps.LatLngBounds שמגדיר את המלבן שבו רוצים לחפש, או
    • 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 השדרה ה-8, ניו-יורק, ניו-יורק" כוללת את הרכיבים הבאים: "111" (מספר הרחוב), "השדרה ה-8" (הנתיב), "ניו-יורק" (העיר) ו-"NY" (המדינה בארה"ב).

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

• geometry: מידע גיאומטרי לגבי המקום. למשל:
  • קו הרוחב location מציין את קווי האורך והרוחב של המקום.
  • viewport מגדיר את אזור התצוגה המועדף במפה כשמציגים את המקום הזה.
• permanently_closed (הוצא משימוש) הוא תכונה ניסיונית בוליאנית המציינת אם המקום נסגר באופן זמני או סופי (ערך true). אין להשתמש ב-permanently_closed. במקום זאת, כדאי להשתמש ב-business_status כדי לקבל את הסטטוס התפעולי של עסקים.
• plus_code (ראו פתיחת קוד מיקום וקוד פלוס) הוא הפניה מקודדת למיקום, שנגזרת מקואורדינטות של קווי אורך ורוחב, שמייצגת אזור: 1/8,000 מעלות במעלה 1/8000 מעלות ממעלות (כ-14 מ' x 14 מ' מקו המשווה) או פחות. ניתן להשתמש ב-Plus Codes כתחליף לכתובות ברחוב במקומות שבהם הם לא קיימים (כשמבנים לא ממוספרים או שלשמות רחובות אין שם).

  הפורמט של ה-Plus Code צריך להיות קוד גלובלי וגם קוד מורכב:

  • global_code הוא קוד אזור של 4 תווים וקוד מקומי בן 6 תווים או יותר (849VCWC8+R9).
  • compound_code הוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש (CWC8+R9, Mountain View, CA, USA). אין לנתח את התוכן הזה באופן פרוגרמטי.
  בדרך כלל מוחזר גם הקוד הגלובלי וגם הקוד המורכב. עם זאת, אם התוצאה היא במיקום מרוחק (לדוגמה, אוקיינוס או מדבר), ניתן להחזיר רק את הקוד הגלובלי.
• html_attributions: מערך השיוכים שצריך להציג כשמציגים את תוצאות החיפוש. כל רשומה במערך מכילה את טקסט ה-HTML לשיוך יחיד. הערה: זהו צבירה של כל השיוך (Attribution) של כל התגובה לחיפוש. לכן, כל PlaceResult האובייקטים בתגובה מכילים רשימות שיוך זהות.
• icon מחזירה את כתובת ה-URL עבור סמל PNG צבעוני בגודל 71 פיקסלים x 71 פיקסלים.
• icon_mask_base_uri מחזירה את כתובת ה-URL הבסיסית לסמל ללא צבעים, ללא הסיומת .svg או .png
• icon_background_color מחזירה את קוד ברירת המחדל של צבע HEX עבור קטגוריית המקום.
• 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

הערה: מומלץ לקרוא את המדריך לשימוש ב-TypeScript ובמפות Google.

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

הערה: קוד ה-JavaScript מורכב מקטע הקוד של ScriptScript.

דוגמה

לדגימה

JSFiddle.net CodeSandbox.io Google Cloud Shell

פרטי מקומות

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

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

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

דוגמה

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

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

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

השדות opening_hours.open_now ו-utc_offset ב-'SDK של מקומות' ל-iOS הוצאו משימוש ב-20 בנובמבר 2019, והם יושבתו ב-20 בפברואר 2021. מידע נוסף

אפשר להשתמש בפרמטר 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 (in,ספרייה 2),utc_offset_minutesvicinity

יצירת קשר

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

אווירה

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

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

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

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

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

קודי סטטוס

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

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

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

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

  הכתובת המפורמטת מורכבת מרכיב כתובת אחד או יותר. לדוגמה, הכתובת "111 השדרה ה-8, ניו-יורק, ניו-יורק" כוללת את הרכיבים הבאים: "111" (מספר הרחוב), "השדרה ה-8" (הנתיב), "ניו-יורק" (העיר) ו-"NY" (המדינה בארה"ב).

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

• formatted_phone_number: מספר הטלפון של המקום, בפורמט בהתאם ל מוסכמה האזורית של המספר.
• geometry: מידע גיאומטרי לגבי המקום. למשל:
  • קו הרוחב location מציין את קווי האורך והרוחב של המקום.
  • viewport מגדיר את אזור התצוגה המועדף במפה כשמציגים את המקום הזה.
• permanently_closed (הוצא משימוש) הוא תכונה ניסיונית בוליאנית המציינת אם המקום נסגר באופן זמני או סופי (ערך true). אין להשתמש ב-permanently_closed. במקום זאת, כדאי להשתמש ב-business_status כדי לקבל את הסטטוס התפעולי של עסקים.
• plus_code (ראו פתיחת קוד מיקום וקוד פלוס) הוא הפניה מקודדת למיקום, שנגזרת מקואורדינטות של קווי אורך ורוחב, שמייצגת אזור: 1/8,000 מעלות במעלה 1/8000 מעלות ממעלות (כ-14 מ' x 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 של המשרד בסידני באוסטרליה, הוא [phone].
• 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 שעות (hhm) (הערכים הם בטווח של 0000–2359). הtime ידווח לפי אזור הזמן של המקום.
    • close עשוי להכיל אובייקטים של יום ושעה שמתארים את סגירת המקום. הערה: אם מקום כלשהו תמיד פתוח, התשובה close תהיה חסרה בתגובה. אפליקציות יכולות להסתמך על כך שהייצוג התמידי יהיה תקופה של open שמכילה את הערך day עם הערך 0 ו-time עם הערך 0000, ולא את הערך close.
  • weekday_text הוא מערך של שבע מחרוזות שמייצגות את שעות הפתיחה בפורמט המתאים לכל יום בשבוע. אם צוין פרמטר language בבקשה לפרטי מיקום, שירות מקומות Google יעצב ויתאים את שעות הפתיחה בשפה הזו. סדר האלמנטים במערך הזה תלוי בפרמטר 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 בסידני, באוסטרליה יש ערך vicinity של 5/48 Pirrama Road, Pyrmont. הנכס vicinity מוחזר רק עבור חיפוש בקרבת מקום.
• website מפרט את האתר המוסמך של מקום זה, כגון דף הבית של עסק.

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

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

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

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

הערה: מזהי מקומות זמינים גם דרך Places API. מזהה של מקום יחיד מתייחס רק למקום אחד, אבל יכול להיות שיש למקום כמה מזהי מקומות. למידע נוסף, קראו את הסקירה הכללית על מזהה מקום.

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

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

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

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

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