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

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

סקירה כללית

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

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

תחילת העבודה

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

הפעלת ממשקי API

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

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

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

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

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

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

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

מכסות

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

מדיניות

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

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

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

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

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

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

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

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

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

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

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

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

  • phoneNumber (חובה) מספר טלפון בפורמט E.164.
  • fields (חובה) שדה אחד או יותר שמציין את הסוגים של נתוני המקום להחזרה.
  • locationBias (אופציונלי) קואורדינטות המגדירות את האזור אל לחפש הישות יכולה להיות אחת מהאפשרויות הבאות:

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

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

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

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

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() methods יש אותה קבוצה של ויכולים להחזיר את אותם שדות בתשובות המתאימות.

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

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

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

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

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

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

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

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

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

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

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

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

חיפוש של 'מקומות בקרבת מקום' מופעל בהפעלה של שיטת nearbySearch() של PlacesService, שתינתן להחזיר מערך של PlaceResult אובייקטים. חשוב לשים לב שnearbySearch() ה-method מחליפה את השיטה search() נכון לגרסה 3.9.

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

חיפושי טקסט מבוצעים באמצעות קריאה ל שיטת 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 שמגדיר את המלבני אזור החיפוש. מרחק האלכסון המקסימלי הנתמך לגבולות הוא בערך 100,000 מטרים.
      • location ו-radius — אפשר תוצאות של הטיה כלפי מעגל שצוין על ידי העברת location ופרמטר radius. הפעולה הזו תגרור להורות לשירות 'מקומות' להעדיף להציג תוצאות במסגרת מעגל. יכול להיות שעדיין יוצגו תוצאות מחוץ לאזור שהוגדר. המיקום לוקח אובייקט google.maps.LatLng, הרדיוס לוקח מספר שלם פשוט, שמייצג את רדיוס המעגל במטרים. הרדיוס המקסימלי המותר הוא 50,000 מטר.
    • type — הגבלת התוצאות למקומות תואמים מהסוג שצוין. ניתן לציין רק סוג אחד (אם יותר מסוג אחד השדה '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 הוא רק שהוחזרו בתגובה לחיפוש טקסט.

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

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

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

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

כדאי לנסות דוגמה

פרטי מקומות

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

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

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

להצגת דוגמה

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

הפרמטר 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, utc_offset (הוצאה משימוש בספריית מקומות Google, Maps JavaScript API), utc_offset_minutes, vicinity

יצירת קשר

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

אווירה

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

מידע נוסף על place 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: כתובת של המקום הזה שאנשים יכולים לקרוא.

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

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

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

  • formatted_phone_number: מספר הטלפון של המקום, בפורמט המתאים בהתאם מוסכמות אזוריות של מספר.
  • geometry: מידע שקשור לגיאומטריה של המקום. הזה כוללת:
    • location מספק את קו הרוחב וקו האורך של במקום.
    • viewport מגדיר את אזור התצוגה המועדף במפה כאשר שמראים את המקום הזה.
  • permanently_closed (הוצאה משימוש) הוא דגל בוליאני שמציין אם המקום נסגר באופן זמני או קבוע (ערך true). לא להשתמש permanently_closed במקום זאת, משתמשים ב-business_status כדי לקבל את הסטטוס התפעולי של עסקים.
  • plus_code (ראו פתיחת קוד המיקום וקודי פלוס) היא הפניה מקודדת למיקום, שנגזרת מקואורדינטות של קווי אורך ורוחב, מייצג שטח: 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, ארה"ב). אין לנתח את התוכן הזה באופן פרוגרמטי.
    בדרך כלל, מוחזרים גם הקוד הגלובלי וגם הקוד המורכב. אבל אם התוצאה מיקום מרוחק (לדוגמה, אוקיינוס או מדבר) ניתן להחזיר רק את הקוד הגלובלי.
  • html_attributions: טקסט השיוך (Attribution) שיוצג עבור את התוצאה של המקום הזה.
  • icon: כתובת URL של מקור תמונות שאפשר להשתמש בו שמייצגים את הסוג של המקום הזה.
  • international_phone_number מכיל את הטלפון של המקום מספר בפורמט בינלאומי. פורמט בינלאומי כולל את שם המדינה ולפניו מופיע סימן הפלוס (+). לדוגמה, international_phone_number לסידני של Google, אוסטרליה המשרד הוא +61 2 9374 4000.
  • name: שם המקום.
  • utc_offset הוצא משימוש בספריית המקומות, ב-JavaScript API של מפות 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', ביקורות טקסט נחשבות אופציונליות; לכן השדה הזה יכול להישאר ריק.
  • types מערך של סוגים של המקום הזה (למשל, ["political", "locality"] או ["restaurant", "lodging"]). המערך הזה עשוי להכיל ערכים מרובים, או להיות ריק. ייתכנו ערכים חדשים ללא הודעה מוקדמת. לצפייה ברשימה של סוגים נתמכים.
  • url: כתובת ה-URL של דף Google הרשמי של הנושא במקום. זהו הדף בבעלות Google שכולל את התוכן הטוב ביותר לקבל מידע זמין על המקום. אפליקציות חייבות לקשר אל או להטמיע אותן את הדף הזה בכל מסך שמציג תוצאות מפורטות לגבי המקום משתמש.
  • vicinity: כתובת פשוטה יותר של המקום, כולל שם הרחוב, מספר הרחוב והרשות המוניציפאלית, אבל לא מחוז/מדינה, מיקוד או מדינה. לדוגמה, סידני של Google, במשרד באוסטרליה, ערך vicinity הוא 5/48 Pirrama Road, Pyrmont. הנכס vicinity מוחזר רק לחיפוש בקרבת מקום.
  • website מציין את האתר המוסמך של המקום הזה, כמו כעסק' דף הבית.

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

שימוש ברכיב 'סקירה כללית של מקום'

הערה: הדוגמה הזו מתבססת על ספריית קוד פתוח. לצפייה README לקבלת תמיכה ומשוב שקשור לספרייה.

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

תמונה שמציגה וריאציות בגדלים x-small, &#39;קטן&#39;, &#39;בינוני&#39;, &#39;גדול&#39; ו-x-גדול רכיב הסקירה הכללית של המקום מוצג על סמך שדה הגודל שהמשתמש הזין.
איור 1: פרטי פרטי המקום בחמש וריאציות שונות של גדלים

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

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

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