דף זה תורגם על ידי Cloud Translation API.

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

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

סקירה כללית

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

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

איך מתחילים

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

הפעלת ממשקי API

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

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

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

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

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

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

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

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

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

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

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

מכסות

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

כללי מדיניות

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

אווירה

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

השיטות findPlaceFromQuery() ו-findPlaceFromPhoneNumber() כוללות את אותה קבוצת שדות, והן יכולות להחזיר את אותם שדות בתשובות שלהן.

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

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

הטייה של תוצאות לאזור ספציפי:

locationBias: {lat: 37.402105, lng: -122.081974}

מגדירים אזור מלבני לחיפוש:

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

אפשר גם להשתמש ב-LatLngBounds.

מגדירים רדיוס לחיפוש (במטרים), שמתמקד באזור מסוים:

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

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

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

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

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

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

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() שיטת קריאה חוזרת (callback) כדי לטפל באובייקט התוצאות ובתגובה 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, ניו יורק, NY" כוללת את הרכיבים הבאים: "111" (מספר הרחוב), "8th Avenue" (המסלול), "New York" (העיר) ו-"NY" (מדינת ארה"ב).

אין לנתח באופן פרוגרמטי את הכתובת בפורמט הנכון. במקום זאת, צריך להשתמש ברכיבי הכתובת הנפרדים, שכלולים בתגובת ה-API בנוסף לשדה הכתובת בפורמט המתאים.
geometry: מידע הקשור לגיאומטריה של המקום. האמצעים האלה כוללים:
- ב-location מוצגים קווי האורך והרוחב של המקום.
- viewport מגדיר את אזור התצוגה המועדף במפה כשצופים במקום הזה.
permanently_closed (הוצא משימוש) הוא סימון בוליאני שמציין אם המקום נסגר לצמיתות או באופן זמני (ערך true). אין להשתמש ב-permanently_closed. במקום זאת, ניתן להשתמש ב-business_status כדי לראות את הסטטוס התפעולי של עסקים.
plus_code (ראו קוד מיקום פתוח וקודי פלוס) הוא הפניה למיקום מקודד, שנגזר מקואורדינטות של קווי אורך ורוחב, שמייצג שטח: 1/8,000 ממעלה 1/8,000 ממעלה (כ-14 מטרים בקו המשווה) או קטן יותר. אפשר להשתמש בקודי Plus כתחליף לכתובות רחובות במקומות שבהם הן לא קיימות (שבהן המבנים אינם ממוספרים או הרחובות לא נקובים).
ה-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 מחזיר את קוד ברירת המחדל של צבע HEX עבור הקטגוריה של המקום.
name: שם המקום.
השדה opening_hours עשוי לכלול את המידע הבא:
- open_now הוא ערך בוליאני שמציין אם המקום פתוח בשעה הנוכחית (הוצא משימוש בספריית המקומות, בממשק JavaScript של מפות Google. במקום זאת, יש להשתמש ב-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

להצגת דוגמה

ניסוי לדוגמה

JSFiddle.net Google Cloud Shell

פרטי מקומות

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

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

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

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

יצירת קשר

קטגוריית אנשי הקשר כוללת את השדות האלה:
formatted_phone_number, international_phone_number, opening_hours, website

אווירה

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

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

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

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

קודי סטטוס

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

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

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

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

address_components: מערך שמכיל את הרכיבים הנפרדים שרלוונטיים לכתובת הזו.
כל רכיב כתובת מכיל בדרך כלל את השדות הבאים:
- types[] הוא מערך שמציין את הסוג של רכיב הכתובת. אפשר לראות את רשימת הסוגים הנתמכים.
- long_name הוא שם הטקסט או תיאור הטקסט המלא של רכיב הכתובת כפי שהוחזר על ידי ה-Geocoder.
- short_name הוא שם טקסטואלי מקוצר של רכיב הכתובת, אם הוא זמין. לדוגמה, רכיב כתובת של מדינת אלסקה עשוי לכלול long_name את "אלסקה" ו-short_name את "AK" באמצעות קיצור בן 2 האותיות.
חשוב לשים לב לעובדות הבאות לגבי המערך address_components[]:
- מערך רכיבי הכתובת יכול להכיל יותר רכיבים מאשר הפונקציה formatted_address.
- המערך לא כולל בהכרח את כל הישויות הפוליטיות שמכילות כתובת, מלבד אלה שכלולות ב-formatted_address. כדי לאחזר את כל הישויות הפוליטיות שמכילות כתובת ספציפית, צריך להשתמש בקידוד גיאוגרפי הפוך, ולהעביר לבקשה את קו הרוחב/קו האורך של הכתובת כפרמטר.
- לא בטוח שפורמט התשובה יישאר זהה בין הבקשות. באופן ספציפי, מספר הaddress_components משתנה בהתאם לכתובת המבוקשת, והוא עשוי להשתנות עם הזמן לגבי אותה כתובת. מיקום רכיב יכול לשנות את מיקום המערך. סוג הרכיב עשוי להשתנות. ייתכן שחסר רכיב מסוים בתגובה מאוחרת יותר.
business_status מציין את סטטוס התפעול של המקום, אם מדובר בעסק. הערך יכול להכיל אחד מהערכים הבאים:
- OPERATIONAL
- CLOSED_TEMPORARILY
- CLOSED_PERMANENTLY
אם לא קיימים נתונים, הערך business_status לא מוחזר.
formatted_address: הכתובת של המקום הזה בפורמט שקריא לבני אדם.
לעיתים קרובות כתובת זו מקבילה לכתובת למשלוח דואר. לתשומת ליבך, במדינות מסוימות, כמו בריטניה, אסור להפיץ כתובות דואר אמיתיות עקב הגבלות רישוי.

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

אין לנתח באופן פרוגרמטי את הכתובת בפורמט הנכון. במקום זאת, צריך להשתמש ברכיבי הכתובת הנפרדים, שכלולים בתגובת ה-API בנוסף לשדה הכתובת בפורמט המתאים.
formatted_phone_number: מספר הטלפון של המקום, בפורמט שתואם למוסכמות האזוריות של המספר.
geometry: מידע הקשור לגיאומטריה של המקום. האמצעים האלה כוללים:
- ב-location מוצגים קווי האורך והרוחב של המקום.
- viewport מגדיר את אזור התצוגה המועדף במפה כשצופים במקום הזה.
permanently_closed (הוצא משימוש) הוא סימון בוליאני שמציין אם המקום נסגר לצמיתות או באופן זמני (ערך true). אין להשתמש ב-permanently_closed. במקום זאת, ניתן להשתמש ב-business_status כדי לראות את הסטטוס התפעולי של עסקים.
plus_code (ראו קוד מיקום פתוח וקודי פלוס) הוא הפניה למיקום מקודד, שנגזר מקואורדינטות של קווי אורך ורוחב, שמייצג שטח: 1/8,000 ממעלה 1/8,000 ממעלה (כ-14 מטרים בקו המשווה) או קטן יותר. אפשר להשתמש בקודי Plus כתחליף לכתובות רחובות במקומות שבהם הן לא קיימות (שבהן המבנים אינם ממוספרים או הרחובות לא נקובים).
ה-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 הוצא משימוש בספריית המקומות, בממשק ה-API של JavaScript של מפות Google, יש להשתמש ב-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 שעות hhmm (הערכים נמצאים בטווח של 0000-2359). time ידווח באזור הזמן של המקום.
  - close עשוי לכלול צמד אובייקטים של יום ושעה שמתארים את שעת הסגירה של המקום. הערה: אם מקום כלשהו פתוח תמיד, הקטע close לא יופיע בתשובה. אפליקציות יכולות להיות מיוצגות תמיד כתקופה של open, שמכילה את הערך day עם הערך 0 ואת הערך time עם הערך 0000, ללא 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+ Local. כשתקבלו מידע על המקום באמצעות בקשה של 'פרטי מקום', יוחזרו קובצי עזר עם צילום של תוכן רלוונטי. הבקשות 'חיפוש בקרבת מקום' ו'חיפוש טקסט' מחזירות גם הפניה אחת של תמונה לכל מקום, לפי הצורך. באמצעות השירות של תמונות Google, תוכלו לגשת לתמונות שמוזכרות ולשנות את הגודל שלהן בהתאם לגודל אופטימלי של האפליקציה.

מערך של 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})
  });
}

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