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

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

סקירה כללית

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

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

תחילת העבודה

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

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

שירות Places הוא ספרייה עצמאית, נפרדת מהקוד הראשי של Maps JavaScript API. כדי להשתמש בפונקציונליות שמכילה הספרייה הזו, צריך קודם לטעון אותה באמצעות הפרמטר libraries בכתובת ה-URL של טעינה ראשונית של 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 לשימוש ב-Places Library, ‏ Maps JavaScript API:

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

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

מכסות

לספריית Places יש מכסת שימוש משותפת עם Places API, כפי שמתואר במסמך 'מגבלות שימוש' של Places API.

מדיניות

השימוש ב-Places Library, ‏ Maps JavaScript API חייב להתבצע בהתאם למדיניות שמפורטת לגבי Places API.

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

בעזרת שירות Places אפשר לבצע את סוגי החיפושים הבאים:

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

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

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

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

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

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

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

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

צריך גם להעביר לשיטה 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);
    }
  });
}

להצגת דוגמה

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

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

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

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

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

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

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

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

Basic

הקטגוריה הבסיסית כוללת את השדות הבאים:
business_status, formatted_address, geometry, icon,icon_mask_base_uri, icon_background_color, name, permanently_closed (הווצא משימוש), photos, place_id, plus_code, types

יצירת קשר

הקטגוריה 'פרטים ליצירת קשר' כוללת את השדה הבא: opening_hours
(הוצא משימוש בספריית המקומות, Maps JavaScript API. משתמשים בבקשה מסוג Place Details כדי לקבל את התוצאות של 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 – ורדיוס, שנמדד במטרים.

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

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

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

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

query (חובה) מחרוזת הטקסט שרוצים לחפש, לדוגמה: 'מסעדה' או 'רחוב ראשי 123'. צריך להזין שם של מקום, כתובת או קטגוריה של מוסד. כל סוג אחר של קלט יכול לגרום לשגיאות, ולא בטוח שיוחזר ממנו תוצאה תקינה. שירות המקומות יחזיר התאמות לפי המחרוזת הזו, ויסדר את התוצאות לפי הרלוונטיות המשוערת שלהן. הפרמטר הזה הופך לאופציונלי אם משתמשים בפרמטר type גם בבקשת החיפוש.
אם רוצים:
- openNow – ערך בוליאני שמציין ששירות Places צריך להחזיר רק את המקומות שפתוח בזמן שליחת השאילתה. אם תכללו את הפרמטר הזה בשאילתה, לא יוצגו מקומות שלא צוינו בהם שעות פתיחה במסד הנתונים של Google Places. להגדרה של openNow לערך false אין השפעה.
- minPriceLevel ו-maxPriceLevel – הגבלת התוצאות רק למקומות ברמת המחיר שצוינה. הערכים החוקיים הם בטווח שבין 0 (הכי זול) ל-4 (הכי יקר), כולל.
- אחת משתי האפשרויות:
  - bounds, שצריך להיות אובייקט google.maps.LatLngBounds שמגדיר את אזור החיפוש המלבני. המרחק המקסימלי באלכסון שנתמך לאזור ההגבלות הוא כ-100,000 מטרים.
  - location ו-radius – אפשר להעביר את הפרמטרים location ו-radius כדי להטות את התוצאות לעיגול מסוים. כך תוכלו להורות לשירות Places להעדיף להציג תוצאות בתוך המעגל הזה. יכול להיות שתוצגו תוצאות מחוץ לאזור שהוגדר. המיקום מקבל אובייקט 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 (הווצא משימוש) הוא סימון בוליאני שמציין אם המקום נסגר באופן קבוע או זמני (ערך 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: כתובת פשוטה של המקום, כולל שם הרחוב, מספר הבית והיישוב, אבל לא את המחוז, המיקוד או המדינה. לדוגמה, הערך של השדה vicinity במשרד של Google בסידני, אוסטרליה הוא 5/48 Pirrama Road, Pyrmont.

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

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

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

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

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

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

להצגת דוגמה

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

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

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

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

יצירת קשר

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

תוצאות של Place Details

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

address_components: מערך שמכיל את הרכיבים הנפרדים שרלוונטיים לכתובת הזו.
בדרך כלל, כל רכיב של כתובת מכיל את השדות הבאים:
- types[] הוא מערך שמציין את הסוג של רכיב הכתובת. כאן אפשר לעיין ברשימת הסוגים הנתמכים.
- long_name הוא התיאור המלא בטקסט או השם של רכיב הכתובת, כפי שהוחזר על ידי המקודד הגיאוגרפי.
- short_name הוא שם מקוצר של רכיב הכתובת, אם הוא זמין. לדוגמה, רכיב כתובת של המדינה אלסקה יכול לכלול את הערך long_name של 'אלסקה' ואת הערך short_name של 'AK', לפי הקיצור הדו-אותי של המדינה.
שימו לב לעובדות הבאות לגבי המערך 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/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 מכיל את מספר הטלפון של המקום בפורמט בינלאומי. הפורמט הבינלאומי כולל את קוד המדינה, ומתחיל בסימן הפלוס (+). לדוגמה, הערך של 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 שעות (hh:mm) (הערכים נעים בטווח 0000 עד 2359). הערך של time ידווח לפי אזור הזמן של המקום.
  - close עשוי להכיל זוג אובייקטים של יום ושעה שמתארים מתי המקום נסגר. הערה: אם המקום פתוח תמיד, הקטע close לא יופיע בתגובה. אפליקציות יכולות להסתמך על כך שחלון תמיד פתוח יהיה מיוצג כתקופה open שמכילה את הערך 0 ב-day ואת הערך 0000 ב-time, ללא close.
- weekday_text הוא מערך של שבע מחרוזות שמייצגות את שעות הפתיחה בפורמט המתאים לכל יום בשבוע. אם הוגדר פרמטר language בבקשה של פרטי המקום, שירות המקומות יארגן ויתרגם את שעות הפתיחה בהתאם לשפה הזו. סדר הרכיבים במערך הזה תלוי בפרמטר language. בשפות מסוימות השבוע מתחיל ביום שני, ובשפות אחרות הוא מתחיל ביום ראשון.
permanently_closed (הווצא משימוש) הוא סימון בוליאני שמציין אם המקום נסגר באופן קבוע או זמני (ערך true). אין להשתמש ב-permanently_closed. במקום זאת, צריך להשתמש ב-business_status כדי לקבל את סטטוס התפעול של העסקים.
photos[]: מערך של אובייקטים מסוג PlacePhoto. אפשר להשתמש ב-PlacePhoto כדי לקבל תמונה באמצעות השיטה getUrl(), או לבדוק את האובייקט כדי למצוא את הערכים הבאים:
- height: הגובה המקסימלי של התמונה, בפיקסלים.
- width: הרוחב המקסימלי של התמונה, בפיקסלים.
- html_attributions: טקסט השיוך שיוצג יחד עם התמונה של המקום.
place_id: מזהה טקסט שמזהה באופן ייחודי מקום, וניתן להשתמש בו כדי לאחזר מידע על המקום באמצעות בקשה לפרטים על מקום. מידע נוסף על הפניה למקום באמצעות מזהה מקום
rating: הדירוג של המקום, בטווח שבין 0.0 ל-5.0, על סמך ביקורות מצטברות של משתמשים.
reviews מערך של עד חמש ביקורות. כל בדיקה מורכבת מכמה רכיבים:
- השדה aspects[] מכיל מערך של אובייקטים מסוג PlaceAspectRating, שכל אחד מהם מספק דירוג של מאפיין יחיד של המלון. האובייקט הראשון במערך נחשב לאספקט הראשי. כל PlaceAspectRating מוגדר כך:
  - type השם של ההיבט שרוצים לדרג. סוגי הנתונים הנתמכים הם: appeal,‏ atmosphere, ‏ decor,‏ facilities, ‏ food, ‏ overall,‏ quality ו-service.
  - rating הדירוג של המשתמש לגבי ההיבט הספציפי הזה, בין 0 ל-3.
- author_name השם של המשתמש ששלח את הביקורת. ביקורות אנונימיות משויכות ל'משתמש Google'. אם הוגדר פרמטר שפה, הביטוי 'משתמש Google' יחזיר מחרוזת מותאמת לשפה.
- author_url כתובת ה-URL של פרופיל Google+ של המשתמש, אם היא זמינה.
- language קוד שפה של IETF שמציין את השפה שבה נכתבה הביקורת של המשתמש. השדה הזה מכיל רק את תג השפה הראשי, ולא את התג המשני שמציין את המדינה או האזור. לדוגמה, כל הביקורות באנגלית מתויגות בתור 'en' ולא 'en-AU' או 'en-UK' וכו'.
- rating הדירוג הכולל של המשתמש למקום הזה. זהו מספר שלם בין 1 ל-5.
- text הביקורת של המשתמש. כשבודקים מיקום ב-Google Places, ביקורות טקסט נחשבות אופציונליות, ולכן יכול להיות שהשדה הזה יהיה ריק.
types מערך של סוגי המקום (למשל, ["political", "locality"] או ["restaurant", "lodging"]). המערך הזה יכול להכיל כמה ערכים, או להיות ריק. ייתכן שנוסיף ערכים חדשים ללא הודעה מוקדמת. כאן אפשר לעיין ברשימת הסוגים הנתמכים.
url: כתובת ה-URL של הדף הרשמי של Google לגבי המקום הזה. זהו הדף שבבעלות Google שמכיל את המידע הטוב ביותר על המקום. האפליקציות חייבות לקשר לדף הזה או להטמיע אותו בכל מסך שבו מוצגות למשתמש תוצאות מפורטות לגבי המקום.
vicinity: כתובת פשוטה של המקום, כולל שם הרחוב, מספר הבית והיישוב, אבל לא את המחוז, המיקוד או המדינה. לדוגמה, הערך של השדה vicinity במשרד של Google בסידני, אוסטרליה הוא 5/48 Pirrama Road, Pyrmont. הנכס vicinity מוחזר רק בחיפוש בקרבת מקום.
website מציג את האתר המהימן של המקום הזה, למשל דף הבית של העסק.

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

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

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

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

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

var map;

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

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

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

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

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

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

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

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

סקירה כללית

תחילת העבודה

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

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

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

מכסות

מדיניות

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

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

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

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

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

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

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

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

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

קודי סטטוס

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

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

TypeScript

JavaScript

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

פרטי מקומות

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

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

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

קודי סטטוס

תוצאות של Place Details

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

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

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