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

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

מפתחים באזור הכלכלי האירופי (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 לרשימת ההגבלות על ממשקי API של מפתח ה-API

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

נכנסים למסוף Google Cloud.
לוחצים על התפריט הנפתח של הפרויקט ובוחרים את הפרויקט שמכיל את מפתח ה-API שרוצים לאבטח.
לוחצים על לחצן התפריט ובוחרים באפשרות פלטפורמת מפות 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 מחזירה מקום על סמך מספר טלפון.
‫Nearby Search מחזירה רשימה של מקומות בסביבה על סמך המיקום של המשתמש.
‫Text Search מחזירה רשימה של מקומות בסביבה על סמך מחרוזת חיפוש, למשל: ‫"Pizza".
בקשות לפרטי מקום מחזירות מידע מפורט יותר על מקום ספציפי, כולל ביקורות של משתמשים.

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

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

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

‫Find Place from Query
איתור מקום לפי מספר טלפון

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

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

‫query (חובה) מחרוזת הטקסט שרוצים לחפש, לדוגמה: 'מסעדה' או 'רחוב ראשי 123'. צריך להזין שם של מקום, כתובת או קטגוריה של עסקים. סוגי קלט אחרים עלולים ליצור שגיאות, ואין ערובה לכך שיוחזרו תוצאות תקינות. ‫Places API יחזיר התאמות אפשריות על סמך המחרוזת הזו, ויסדר את התוצאות לפי מידת הרלוונטיות שלהן.
‫fields (חובה) שדה אחד או יותר שמציינים את סוגי הנתונים של המקום שיוחזרו.
‫locationBias (אופציונלי) קואורדינטות שמגדירות את האזור לחיפוש. הפרטים יכולים להיות:
- קבוצה של קואורדינטות של קו רוחב/אורך שצוינו כ-LatLngLiteral או כ-LatLng object
- גבולות מלבניים (שני זוגות של קווי רוחב/אורך, או אובייקט 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 מקבלת מספר טלפון ומחזירה מקום. כדי לשלוח בקשה לחיפוש מקום לפי מספר טלפון, קוראים לשיטה PlacesService של findPlaceFromPhoneNumber(), שמקבלת את הפרמטרים הבאים:

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

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

שדות (שיטות Find Place)

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

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

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

אטמוספרה

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

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

הגדרת הטיה למיקום (שיטות Find Place)

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

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

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

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

query (חובה) מחרוזת הטקסט של החיפוש, למשל: 'מסעדה' או 'רחוב ראשי 123'. הערך צריך להיות שם של מקום, כתובת או קטגוריה של בתי עסק. סוגי קלט אחרים עלולים ליצור שגיאות, ואין ערובה לכך שיוחזרו תוצאות תקינות. שירות המקומות יחזיר התאמות אפשריות על סמך המחרוזת הזו, ויסדר את התוצאות לפי מידת הרלוונטיות שלהן. הפרמטר הזה הופך לאופציונלי אם משתמשים גם בפרמטר type בבקשת החיפוש.
אופציונלי:
- ‫openNow – ערך בוליאני שמציין ששירות המקומות צריך להחזיר רק את המקומות שפתוחים לעסקים בזמן שליחת השאילתה. אם לא צוינו שעות פתיחה במקומות מסוימים במסד הנתונים של 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 (deprecated) הוא סימון בוליאני שמציין אם המקום נסגר לצמיתות או באופן זמני (הערך true). אין להשתמש ב-permanently_closed. במקום זאת, אפשר להשתמש בשיטה business_status כדי לקבל את סטטוס הפעילות של עסקים.
‫plus_code (ראו Open Location Code וPlus Codes) הוא הפניה מקודדת למיקום, שנגזרת מקואורדינטות של קו רוחב וקו אורך, ומייצגת אזור: 1/8000 של מעלה על 1/8000 של מעלה (בערך 14 מ' על 14 מ' בקו המשווה) או קטן יותר. אפשר להשתמש ב-Plus Codes במקום בכתובות של רחובות במקומות שבהם אין כתובות כאלה (במקומות שבהם הבניינים לא ממוספרים או שהרחובות לא נקראים בשם).
ה-Plus Code מפורמט כקוד גלובלי וכקוד מורכב:
- ‫global_code הוא קוד אזור בן 4 תווים וקוד מקומי בן 6 תווים או יותר (849VCWC8+R9).
- ‫compound_code הוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש (CWC8+R9, Mountain View, CA, USA). אל תנתחו את התוכן הזה באופן פרוגרמטי.
בדרך כלל, הפונקציה מחזירה גם את הקוד הגלובלי וגם את הקוד המורכב. עם זאת, אם התוצאה היא במיקום מרוחק (לדוגמה, באוקיינוס או במדבר), יכול להיות שיוחזר רק הקוד הגלובלי.
‫html_attributions: מערך של שיוכים שצריך להציג כשמציגים את תוצאות החיפוש. כל רשומה במערך מכילה את טקסט ה-HTML של שיוך יחיד. הערה: זהו צבירה של כל השיוכים לתגובת החיפוש כולה. לכן, כל אובייקט PlaceResult בתשובה מכיל רשימות שיוך זהות.
‫icon מחזירה את כתובת ה-URL של סמל PNG צבעוני בגודל ‎71px x 71px.
‫icon_mask_base_uri מחזירה את כתובת ה-URL הבסיסית של סמל לא צבעוני, ללא הסיומת ‎ .svg או ‎ .png.
‫icon_background_color מחזירה את קוד הצבע ההקסדצימלי שמוגדר כברירת מחדל לקטגוריה של המקום.
‫name: שם המקום.
opening_hours עשוי להכיל את הפרטים הבאים:
- ‫open_now הוא ערך בוליאני שמציין אם המקום פתוח בשעה הנוכחית (הוצא משימוש בספריית המקומות, Maps JavaScript API, צריך להשתמש במקומו ב-utc_offset_minutes).
‫place_id הוא מזהה טקסטואלי שמזהה מקום באופן ייחודי. כדי לאחזר מידע על המקום, מעבירים את המזהה הזה בבקשה לפרטי מקום. מידע נוסף על הפניה למקום באמצעות מזהה מקום
‫rating מכיל את דירוג המקום, מ-0.0 עד 5.0, על סמך ביקורות מצטברות של משתמשים.
types מערך של סוגים של המקום הזה (למשל, ‫["political", "locality"] או ["restaurant", "lodging"]). המערך הזה יכול להכיל כמה ערכים או להיות ריק. יכול להיות שיוצגו ערכים חדשים ללא הודעה מוקדמת. רשימת הסוגים הנתמכים
‫vicinity: כתובת פשוטה של המקום, כולל שם הרחוב, מספר הבית והיישוב, אבל לא המחוז/המדינה, המיקוד או המדינה. לדוגמה, למשרד של 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

להצגת דוגמה

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

JSFiddle.net Google Cloud Shell

פרטי מקומות

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

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

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

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

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

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

תשובות לשאלות על מקומות

קודי סטטוס

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

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

אל תנתחו את הכתובת המעוצבת באופן פרוגרמטי. במקום זאת, צריך להשתמש ברכיבי הכתובת הנפרדים, שהתשובה של ה-API כוללת בנוסף לשדה של הכתובת המעוצבת.
‫formatted_phone_number: מספר הטלפון של המקום, בפורמט שמותאם למוסכמות האזוריות של המספר.
‫geometry: מידע שקשור לגיאומטריה של המקום. הם כוללים:
- ‫location מחזירה את קו הרוחב וקו האורך של המקום.
- ‫viewport מגדיר את אזור התצוגה המועדף במפה כשמציגים את המקום הזה.
‫permanently_closed (deprecated) הוא סימון בוליאני שמציין אם המקום נסגר לצמיתות או באופן זמני (הערך true). אין להשתמש ב-permanently_closed. במקום זאת, אפשר להשתמש בשיטה business_status כדי לקבל את סטטוס הפעילות של עסקים.
‫plus_code (ראו Open Location Code וPlus Codes) הוא הפניה מקודדת למיקום, שנגזרת מקואורדינטות של קו רוחב וקו אורך, ומייצגת אזור: 1/8000 של מעלה על 1/8000 של מעלה (בערך 14 מ' על 14 מ' בקו המשווה) או קטן יותר. אפשר להשתמש ב-Plus Codes במקום בכתובות של רחובות במקומות שבהם אין כתובות כאלה (במקומות שבהם הבניינים לא ממוספרים או שהרחובות לא נקראים בשם).
ה-Plus Code מפורמט כקוד גלובלי וכקוד מורכב:
- ‫global_code הוא קוד אזור בן 4 תווים וקוד מקומי בן 6 תווים או יותר (849VCWC8+R9).
- ‫compound_code הוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש (CWC8+R9, Mountain View, CA, USA). אל תנתחו את התוכן הזה באופן פרוגרמטי.
בדרך כלל, הפונקציה מחזירה גם את הקוד הגלובלי וגם את הקוד המורכב. עם זאת, אם התוצאה היא במיקום מרוחק (לדוגמה, באוקיינוס או במדבר), יכול להיות שיוחזר רק הקוד הגלובלי.
‫html_attributions: טקסט הייחוס שיוצג לתוצאת המקום הזו.
‫icon: כתובת URL למשאב תמונה שאפשר להשתמש בו כדי לייצג את סוג המקום הזה.
‫international_phone_number מכיל את מספר הטלפון של המקום בפורמט בינלאומי. הפורמט הבינלאומי כולל את קוד המדינה, ומתחיל בסימן הפלוס (+). לדוגמה, קוד המדינה של משרד Google בסידני, אוסטרליה, הוא +61 2 9374 4000.international_phone_number
‫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 עם פרטי מקום זמינות בסרטון איך מקבלים שעות פתיחה ב-Places API). ‫`open_now` הוא ערך בוליאני שמציין אם המקום פתוח בזמן הנוכחי.
- ‫periods[] הוא מערך של תקופות פתיחה שכולל שבעה ימים, החל מיום ראשון, בסדר כרונולוגי. כל תקופה כוללת:
  - ‫open מכיל זוג של אובייקטים של יום ושעה שמתארים את שעת הפתיחה של המקום:
    - ‫day מספר מ-0 עד 6, שמתאים לימי השבוע, החל מיום ראשון. לדוגמה, 2 מייצג את יום שלישי.
    - time יכול להכיל שעה בפורמט של 24 שעות hhmm (הערכים הם בטווח 0000 עד 2359). הערך של time ידווח לפי אזור הזמן של המקום.
  - ‫close עשוי להכיל זוג של אובייקטים של יום ושעה שמתארים מתי המקום נסגר. הערה: אם מקום פתוח תמיד, הקטע close לא יופיע בתגובה. אפליקציות יכולות להסתמך על כך ששעות הפתיחה הן תמיד open, שמוצגות כפרק זמן open שמכיל את הערך 0 במאפיין day ואת הערך 0000 במאפיין time, ואין בו מאפיין close.
- ‫weekday_text הוא מערך של שבע מחרוזות שמייצגות את שעות הפתיחה המעוצבות לכל יום בשבוע. אם צוין פרמטר language בבקשה של פרטי המקום, שירות המקומות יתאים את הפורמט של שעות הפתיחה לשפה שצוינה. הסדר של הרכיבים במערך הזה תלוי בפרמטר language. בשפות מסוימות השבוע מתחיל ביום שני, ובשפות אחרות הוא מתחיל ביום ראשון.
‫permanently_closed (deprecated) הוא סימון בוליאני שמציין אם המקום נסגר לצמיתות או באופן זמני (הערך 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: כתובת פשוטה של המקום, כולל שם הרחוב, מספר הבית והיישוב, אבל לא המחוז/המדינה, המיקוד או המדינה. לדוגמה, למשרד של Google בסידני, אוסטרליה, יש ערך vicinity של 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);

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

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

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

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

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

אפשר לבקש את כתובת ה-URL של התמונה המשויכת על ידי הפעלת השיטה PlacePhoto.getUrl() והעברת אובייקט PhotoOptions תקין. משתמשים באובייקט PhotoOptions כדי לציין את הגובה והרוחב המקסימליים של התמונה. אם תציינו ערך גם ל-maxHeight וגם ל-maxWidth, שירות התמונות ישנה את גודל התמונה לגודל הקטן מבין השניים, תוך שמירה על יחס הגובה-רוחב המקורי.

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

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35})
  });
}

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

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

סקירה כללית

תחילת העבודה

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

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

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

מכסות

מדיניות

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

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

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

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

שדות (שיטות Find Place)

הגדרת הטיה למיקום (שיטות Find Place)

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

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

חיפוש תשובות

קודי סטטוס

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

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

TypeScript

JavaScript

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

פרטי מקומות

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

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

תשובות לשאלות על מקומות

קודי סטטוס

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

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

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

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