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

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

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

סקירה כללית

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

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

תחילת העבודה

אם לא השתמשת ב-API של JavaScript במפות Google או ב-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 בממשק API או ב-SDK אחד או יותר. בקשות ל-API או ל-SDK שמשויכים למפתח ה-API יעובדו. בקשות ל-API או ל-SDK שלא משויכים למפתח ה-API ייכשלו. כדי להגביל מפתח API לשימוש עם ספריית המקומות, Maps JavaScript API:

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

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

מכסות

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

כללי מדיניות

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

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

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

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

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

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

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

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

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

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

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

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

בדוגמה הבאה מוצגת קריאה ל-findPlaceFromQuery(), שמחפשת את "המוזיאון לאומנות עכשווית באוסטרליה", ומחפשת את השדות name ו-geometry.

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

  map = new google.maps.Map(
      document.getElementById('map'), {center: sydney, zoom: 15});

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

  var service = new google.maps.places.PlacesService(map);

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}

לצפייה בדוגמה

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

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

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

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

חיפוש של מקומות בקרבת מקום מתחיל בקריאה ל-method nearbySearch() של PlacesService, שתחזיר מערך של אובייקטים של PlaceResult. חשוב לשים לב שהשיטה 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 textSearch() של PlacesService.

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

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

query (חובה) מחרוזת הטקסט שבה מחפשים, לדוגמה: "restaurant" או "123 Main Street". השם צריך להיות שם, כתובת או קטגוריה של מוסדות. סוגים אחרים של קלט עלולים לגרום לשגיאות ולא בטוח שיוצגו תוצאות תקינות. שירות 'מקומות' יחזיר התאמות אפשריות על סמך המחרוזת הזו, ויסדר את התוצאות לפי מידת הרלוונטיות שלהן. הפרמטר הזה הופך לאופציונלי אם נעשה שימוש בפרמטר type גם בבקשת החיפוש.
אם רוצים:
- openNow - ערך בוליאני, המציין ששירות 'מקומות' צריך להחזיר רק את המקומות שפתוחים לעסקים בזמן שליחת השאילתה. מקומות שאינם מציינים שעות פתיחה במסד הנתונים של מקומות Google לא יוחזרו אם תכלול פרמטר זה בשאילתה שלך. אם המדיניות openNow מוגדרת לערך false אין השפעה.
- minPriceLevel ו-maxPriceLevel — מגבילים את התוצאות רק למקומות שנכללים ברמת המחיר שצוינה. הערכים החוקיים נעים בין 0 (הכי זול) עד 4 (היקר ביותר), כולל.
- אחד מהשניים:
  - bounds – אובייקט google.maps.LatLngBounds שמגדיר את המלבן שבו יתבצע החיפוש, או
  - location ו-radius — אפשר להטות את התוצאות למעגל מסוים על ידי העברת הפרמטר location ופרמטר radius. פעולה זו מורה לשירות 'מקומות' להעדיף להציג תוצאות בתוך אותו מעגל. ייתכן שעדיין יוצגו תוצאות מחוץ לאזור המוגדר. המיקום מקבל אובייקט google.maps.LatLng, והרדיוס לוקח מספר שלם פשוט שמייצג את רדיוס המעגל במטרים. הרדיוס המקסימלי המותר הוא 50 000 מטר.
- type - מגביל את התוצאות למקומות התואמים לסוג שצוין. אפשר לציין רק סוג אחד (אם יצוינו יותר מסוג אחד, המערכת תתעלם מכל הסוגים שמופיעים אחרי הרשומה הראשונה). כדאי לעיין ברשימת הסוגים הנתמכים.

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

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    query: 'restaurant'
  };

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

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

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

קודי סטטוס

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

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

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

הפונקציות findPlace(), nearbySearch() ו-textSearch() מחזירות מערך של אובייקטים מסוג PlaceResult.

כל אובייקט PlaceResult עשוי לכלול את המאפיינים הבאים:

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

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

אל תנתחו את הכתובת בפורמט פרוגרמטי. במקום זאת, צריך להשתמש ברכיבי הכתובת הנפרדים, שכוללים את תגובת ה-API בנוסף לשדה הכתובת המעוצב.
geometry: מידע הקשור לגיאומטריה של המקום. האמצעים האלה כוללים:
- location מציין את קווי האורך והרוחב של המקום.
- viewport מגדיר את אזור התצוגה המועדף במפה כשצופים במקום הזה.
permanently_closed (הוצא משימוש) הוא סימון בוליאני שמציין אם המקום נסגר לצמיתות או באופן זמני (ערך true). אין להשתמש ב-permanently_closed. במקום זאת, צריך להשתמש ב-business_status כדי לראות את הסטטוס התפעול של עסקים.
plus_code (מידע נוסף זמין במאמר Open Location Code ו-plus Codes) הוא הפניה למיקום מקודדת, שנגזר מקואורדינטות של קווי אורך ורוחב, שמייצג שטח: 1/8,000 ממעלה 1/8,000 ממעלה (בערך 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 של ייחוס אחד. הערה: זהו צבירה של כל השיוך של כל תגובת החיפוש. לכן, כל PlaceResult האובייקטים בתשובה מכילים רשימות שיוך זהות.
icon מחזירה את כתובת ה-URL של סמל PNG צבעוני בגודל 71px x 71px.
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: כתובת פשוטה יותר של המקום, שכוללת את שם הרחוב, מספר הרחוב והאזור, אבל לא את המחוז/המדינה, המיקוד או המדינה. לדוגמה, ערך 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

פרטי מקומות

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

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

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

השדות תואמים לתוצאות של פרטי מקום ומחולקים לשלוש קטגוריות חיוב: Basic, Contact ו-Atmosphere. השדות הבסיסיים מחויבים בתעריף הבסיסי, ולא כרוכים בחיוב נוסף. החיוב על שדות 'יצירת קשר' ו'אטמוספירה' גבוה יותר. למידע נוסף, ראו גיליון תמחור. השיוך (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, /de JavaScript, ב-API}/Googleutc_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[] הוא מערך שמציין את ה-type של רכיב הכתובת. אפשר לעיין ברשימת הסוגים הנתמכים.
- 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, New York, NY" מורכבת מהרכיבים הבאים: "111" (מספר הרחוב), "8th Avenue" (המסלול), "New York" (העיר) ו-"NY" (מדינת ארה"ב).

אל תנתחו את הכתובת בפורמט פרוגרמטי. במקום זאת, צריך להשתמש ברכיבי הכתובת הנפרדים, שכוללים את תגובת ה-API בנוסף לשדה הכתובת המעוצב.
formatted_phone_number: מספר הטלפון של המקום, בפורמט תואם למוסכמות האזוריות של המספר.
geometry: מידע הקשור לגיאומטריה של המקום. האמצעים האלה כוללים:
- location מציין את קווי האורך והרוחב של המקום.
- viewport מגדיר את אזור התצוגה המועדף במפה כשצופים במקום הזה.
permanently_closed (הוצא משימוש) הוא סימון בוליאני שמציין אם המקום נסגר לצמיתות או באופן זמני (ערך true). אין להשתמש ב-permanently_closed. במקום זאת, צריך להשתמש ב-business_status כדי לראות את הסטטוס התפעול של עסקים.
plus_code (מידע נוסף זמין במאמר Open Location Code ו-plus Codes) הוא הפניה למיקום מקודדת, שנגזר מקואורדינטות של קווי אורך ורוחב, שמייצג שטח: 1/8,000 ממעלה 1/8,000 ממעלה (בערך 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 של משרד Google בסידני באוסטרליה הוא +61 2 9374 4000.
name: שם המקום.
utc_offset הוצא משימוש בספריית המקומות, Maps JavaScript API, יש להשתמש במקום זאת ב-utc_offset_minutes.
utc_offset_minutes מכיל את מספר הדקות שאזור הזמן הנוכחי של המקום הזה מקוזז משעון UTC. לדוגמה, עבור מקומות בסידני שבאוסטרליה במהלך שעון קיץ, יוצג הערך 660 (+11 שעות משעון UTC), ולמקומות בקליפורניה מחוץ לשעון קיץ יוצג הערך -480 (פחות 8 שעות משעון UTC).
opening_hours מכיל את המידע הבא:
- open_now (הוצא משימוש בספריית המקומות, Maps JavaScript API. במקומו צריך להשתמש ב-opening_hours.isOpen(). בסרטון הזה מוסבר איך להשתמש ב-isOpen עם פרטי המקום.) הוא ערך בוליאני שמציין אם המקום פתוח בשעה הנוכחית.
- periods[] הוא מערך של תקופות פתיחה שמתפרסות על פני שבעה ימים, החל מיום ראשון, בסדר כרונולוגי. כל תקופה כוללת:
  - open מכיל צמד של אובייקטים של יום ושעה שמתארים את שעת הפתיחה של המקום:
    - day מספר מ-0 עד 6, התואם לימים בשבוע, החל מיום ראשון. לדוגמה, 2 פירושו יום שלישי.
    - time עשוי להכיל את השעה ביום בפורמט של 24 שעות 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 את כתובת האתר לפרופיל Google+ של המשתמש, אם הוא זמין.
- language קוד שפה IETF שמציין את השפה שבה נעשה שימוש בביקורת של המשתמש. השדה הזה מכיל את תג השפה הראשי בלבד, ולא את התג המשני שמציין מדינה או אזור. לדוגמה, כל הביקורות באנגלית מתויגות בתור 'en', לא 'en-AU' או 'en-UK' וכו'.
- rating הדירוג הכולל של המשתמש לגבי המקום הזה. זהו מספר שלם שנע בין 1 ל-5.
- text את הביקורת של המשתמש. כשבודקים מיקום ב-Google Places, ביקורות טקסט נחשבות לאופציונליות, ולכן יכול להיות שהשדה הזה יהיה ריק.
types מגוון סוגים של המקום הזה (למשל, ["political", "locality"] או ["restaurant", "lodging"]). המערך הזה יכול להכיל כמה ערכים, או שהוא ריק. ייתכן שיתווספו ערכים חדשים ללא הודעה מוקדמת. אפשר לעיין ברשימת הסוגים הנתמכים.
url: כתובת ה-URL של דף Google הרשמי של המקום הזה. זהו הדף בבעלות Google שמכיל את המידע הזמין הטוב ביותר על המקום. אפליקציות חייבות לקשר לדף הזה או להטמיע אותו בכל מסך שמציג למשתמש תוצאות מפורטות על המקום.
vicinity: כתובת פשוטה יותר של המקום, שכוללת את שם הרחוב, מספר הרחוב והאזור, אבל לא את המחוז/המדינה, המיקוד או המדינה. לדוגמה, ערך vicinity במשרדי Google באוסטרליה הוא 5/48 Pirrama Road, Pyrmont. המאפיין vicinity מוחזר רק עבור חיפוש בקרבת מקום.
website מציין את האתר המוסמך של המקום הזה, כמו דף הבית של עסק.

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

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

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

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

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

var map;

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

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

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

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

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

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

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

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