סקירה כללית
הפונקציות של ספריית המקומות, API של Maps JavaScript API, מאפשרות לאפליקציה לחפש מקומות (שמוגדרים ב-API הזה כמוסדות, מיקומים גיאוגרפיים או נקודות עניין בולטות) שנמצאים באזור מוגדר, כמו גבולות מפה או סביב נקודה קבועה.
ממשק API של מקומות Google כולל תכונת השלמה אוטומטית, שבעזרתה ניתן להגדיר לאפליקציות שלך את התנהגות החיפוש מראש, שמו של שדה החיפוש של מפות Google. כשמשתמש מתחיל להקליד כתובת, ההשלמה האוטומטית תמלא את השאר. למידע נוסף, אפשר לעיין בתיעוד של ההשלמה האוטומטית.
איך מתחילים
אם לא ידוע לך מהו הממשק Maps JavaScript API או JavaScript, מומלץ לבדוק את JavaScript ולקבל מפתח API לפני שתתחילו.
הפעלת ממשקי API
לפני השימוש בספריית מקומות Google ב-API JavaScript של מפות Google, יש לוודא תחילה ש- Places API מופעל במסוף Google Cloud, באותו פרויקט שבו הגדרת את Maps JavaScript API.
כדי להציג את רשימת ממשקי ה-API המופעלים:
- נכנסים למסוף Google Cloud.
- לוחצים על הלחצן Select a project (בחירת פרויקט), בוחרים את הפרויקט שהגדרתם עבור Maps JavaScript API ולוחצים על Open.
- ברשימת ממשקי ה-API שבמרכז השליטה, מחפשים את Places API.
- אם Places API מופיע ברשימה, הוא כבר מופעל. אם ממשק ה-API
לא מופיע ברשימה, מפעילים אותו:
- בחלק העליון של הדף, לוחצים על ENABLE APIS AND SERVICES כדי להציג את הכרטיסייה Library. לחלופין, בתפריט הימני לוחצים על ספרייה.
- צריך לחפש את האפשרות Places API ולבחור אותה מרשימת התוצאות.
- בוחרים באפשרות הפעלה. בסיום התהליך, יופיע Places API ברשימת ממשקי ה-API במרכז השליטה.
הספרייה נטענת
שירות המקומות הוא ספרייה עצמאית, שנפרדת מקוד ה-API הראשי של JavaScript של מפות Google. כדי להשתמש בפונקציונליות שכלולה בספרייה הזו, קודם צריך לטעון אותה באמצעות הפרמטר libraries
בכתובת ה-URL לאתחול של API של מפות Google:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>
מידע נוסף זמין בסקירה הכללית של הספריות.
הוספת Places API לרשימת ההגבלות של מפתח ה-API
החלה של הגבלות על ממשקי API על המפתחות מגבילה את השימוש במפתח ה-API לממשק API או ל-SDK אחד או יותר. המערכת תעבד בקשות ל-API או ל-SDK שמשויכים למפתח ה-API. בקשות ל-API או ל-SDK שלא משויכים למפתח ה-API ייכשלו. כדי להגביל מפתח API לשימוש עם ספריית המקומות, Maps JavaScript API:- נכנסים למסוף Google Cloud.
- לוחצים על התפריט הנפתח של הפרויקט ובוחרים את הפרויקט שמכיל את מפתח ה-API שרוצים לאבטח.
- לוחצים על לחצן התפריט
ובוחרים באפשרות הפלטפורמה של מפות Google > פרטי כניסה.
- בדף Credentials, לוחצים על השם של מפתח ה-API שרוצים לאבטח.
- בדף Restrict andRename key API, מגדירים את ההגבלות:
- הגבלות על ממשקי API
- בוחרים באפשרות Restrict key.
- לוחצים על Select APIs (בחירת ממשקי API) ובוחרים גם את Maps JavaScript API וגם את Places API.
(אם אחד מממשקי ה-API לא מופיע ברשימה, צריך enable אותו).
- לוחצים על שמירה.
מגבלות שימוש ומדיניות
מכסות
ספריית המקומות חולקת מכסת שימוש עם Places API, כפי שמתואר במסמכי התיעוד בנושא מגבלות השימוש של Places API.
כללי מדיניות
השימוש בספריית המקומות, Maps JavaScript API חייב להיות בהתאם למדיניות שמתוארת ב- Places API.
חיפושי מקומות
בעזרת השירות 'מקומות' ניתן לבצע את סוגי החיפושים הבאים:
- חיפוש מקום מהשאילתה מחזיר מקום על סמך שאילתת טקסט (למשל, שם או כתובת של מקום).
- חיפוש מקום ממספר הטלפון מחזירה מקום על סמך מספר הטלפון.
- חיפוש בקרבת מקום מחזיר רשימה של מקומות בקרבת מקום על סמך המיקום של המשתמש.
- חיפוש טקסט מחזירה רשימה של מקומות קרובים על סמך מחרוזת חיפוש, לדוגמה: "פיצה".
- בקשות לפרטי מקום מחזירות מידע מפורט יותר לגבי מקום ספציפי, כולל ביקורות של משתמשים.
המידע שמוחזר יכול לכלול מוסדות, כמו מסעדות, חנויות ומשרדים, וכן תוצאות 'גיאוגרפי', שמציינות כתובות, אזורים פוליטיים כמו יישובים וערים ונקודות עניין אחרות.
חיפוש בקשות למקומות
בקשת 'חיפוש מקום' מאפשרת לך לחפש מקום לפי שאילתת טקסט או מספר טלפון. יש שני סוגים של בקשות לחיפוש מקום:
חיפוש מקום מהשאילתה
התכונה 'חיפוש מקום מהשאילתה' מקבלת קלט טקסט ומחזירה מקום. הקלט יכול להיות כל סוג של נתוני מקום, כמו שם עסק או כתובת. כדי לבצע בקשת חיפוש מקום מהשאילתה, צריך לבצע קריאה ל-method findPlaceFromQuery()
של PlacesService
, שמקבל את הפרמטרים הבאים:
query
(חובה) מחרוזת הטקסט שבה רוצים לחפש, לדוגמה: "מסעדה" או "רחוב ראשי 123". השם צריך להיות שם של מקום, כתובת או קטגוריה של מוסדות. כל סוג אחר של קלט יכול לגרום לשגיאות ולא בטוח להחזיר תוצאות תקינות. ממשק ה-API של מקומות Google יחזיר התאמות אפשריות על סמך המחרוזת הזו, ויסדר את התוצאות לפי הרלוונטיות שלהן.fields
(חובה) שדה אחד או יותר לציון הסוגים של נתוני מקום להחזרה.locationBias
(אופציונלי) קואורדינטות המגדירות את האזור לחיפוש. יכול להיות שמדובר באחת מהאפשרויות הבאות:- קבוצת קואורדינטות של קווי אורך ורוחב שמצוינות כLatLngLiteral או כאובייקט LatLng
- גבולות מלבניים (שני צמדי רוחב/אורך, או אובייקט LatLngBounds)
- רדיוס (במטרים) במרכז בקו רוחב/ליטר
בנוסף, צריך להעביר שיטת קריאה חוזרת אל findPlaceFromQuery()
כדי לטפל באובייקט התוצאות ובתגובה google.maps.places.PlacesServiceStatus
.
בדוגמה הבאה מוצגת קריאה ל-findPlaceFromQuery()
, שמחפשת את 'המוזיאון לאומנות עכשווית של אוסטרליה', כולל השדות name
ו-geometry
.
var map; var service; var infowindow; function initMap() { var sydney = new google.maps.LatLng(-33.867, 151.195); infowindow = new google.maps.InfoWindow(); map = new google.maps.Map( document.getElementById('map'), {center: sydney, zoom: 15}); var request = { query: 'Museum of Contemporary Art Australia', fields: ['name', 'geometry'], }; var service = new google.maps.places.PlacesService(map); service.findPlaceFromQuery(request, function(results, status) { if (status === google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } map.setCenter(results[0].geometry.location); } }); }להצגת דוגמה
חיפוש מקום ממספר הטלפון
חיפוש מקום ממספר הטלפון מקבל מספר טלפון ומחזיר מקום. כדי לשלוח בקשת 'חיפוש מקום ממספר הטלפון', צריך לבצע קריאה ל-method findPlaceFromPhoneNumber()
של PlacesService
, שמקבלת את הפרמטרים הבאים:
phoneNumber
(חובה) מספר טלפון, בפורמט E.164.fields
(חובה) שדה אחד או יותר לציון הסוגים של נתוני מקום להחזרה.locationBias
(אופציונלי) קואורדינטות המגדירות את האזור לחיפוש. יכול להיות שמדובר באחת מהאפשרויות הבאות:- קבוצת קואורדינטות של קווי אורך ורוחב שמצוינות כLatLngLiteral או כאובייקט LatLng
- גבולות מלבניים (ארבע נקודות רוחב/אורך, או אובייקט LatLngBounds)
- רדיוס (במטרים) במרכז בקו רוחב/ליטר
בנוסף, צריך להעביר שיטת קריאה חוזרת אל findPlaceFromPhoneNumber()
כדי לטפל באובייקט התוצאות ובתגובה google.maps.places.PlacesServiceStatus
.
שדות (שיטות חיפוש מקום)
צריך להשתמש בפרמטר fields
כדי לציין מערך של סוגי נתוני מקומות שיוחזרו.
לדוגמה: fields: ['formatted_address', 'opening_hours', 'geometry']
כשמציינים ערכים מורכבים, צריך להשתמש בנקודה. לדוגמה: opening_hours.weekday_text
השדות תואמים לתוצאות החיפוש במקום והם מחולקים לשלוש קטגוריות חיוב: Basic, Contact ו-Atmosphere. השדות הבסיסיים מחויבים לפי התעריף הבסיסי, ולא כרוכים בחיובים נוספים. השדות 'יצירת קשר' ו'אטמוספירה' מחויבים בתעריף גבוה יותר. מידע נוסף זמין בגיליון התמחור. השיוך (html_attributions
) תמיד מוחזר בכל קריאה, גם אם הוגשה בקשה לשדה.
Basic
הקטגוריה הבסיסית כוללת את השדות הבאים:
business_status
, formatted_address
, geometry
,
icon
,icon_mask_base_uri
, icon_background_color
,
name
, permanently_closed
(הוצא משימוש),
photos
, place_id
, plus_code
, types
יצירת קשר
הקטגוריה 'אנשי קשר' כוללת את השדה הבא:opening_hours
(הוצאה משימוש ב'ספריית מקומות', ב-API JavaScript של מפות Google. משתמשים בבקשה של פרטי מקום כדי לקבל את התוצאות של
opening_hours
).
אווירה
קטגוריית 'אטמוספירה' כוללת את השדות הבאים:price_level
, rating
, user_ratings_total
השיטות findPlaceFromQuery()
ו-findPlaceFromPhoneNumber()
כוללות את אותה קבוצת שדות, והן יכולות להחזיר את אותם שדות בתשובות שלהן.
הגדרה של הטיה לפי מיקום (שיטות לאיתור מקום)
אפשר להשתמש בפרמטר locationBias
כדי להפוך את התוצאות של 'חיפוש מקום' למועדפים באזור מסוים. תוכלו להגדיר את locationBias
בדרכים הבאות:
הטייה של תוצאות לאזור ספציפי:
locationBias: {lat: 37.402105, lng: -122.081974}
מגדירים אזור מלבני לחיפוש:
locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}
אפשר גם להשתמש ב-LatLngBounds.
מגדירים רדיוס לחיפוש (במטרים), שמתמקד באזור מסוים:
locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}
בקשות לחיפוש בקרבת מקום
חיפוש בקרבת מקום מאפשר לך לחפש מקומות באזור מסוים לפי מילת מפתח או סוג. חיפוש בקרבת מקום צריך תמיד לכלול מיקום, שניתן לציין אותו באחת משתי דרכים:
-
LatLngBounds
. - שטח מעגלי שמוגדר כשילוב של המאפיין
location
— שמציין את מרכז המעגל כאובייקטLatLng
— ורדיוס, שנמדד במטרים.
חיפוש של מקומות קרובים מופעל על ידי קריאה ל-method
PlacesService
, שתחזיר מערך של אובייקטים של
PlaceResult
.nearbySearch()
חשוב לשים לב שהשיטה nearbySearch()
מחליפה את השיטה search()
בגרסה 3.9.
service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback);
השיטה הזו מקבלת בקשה עם השדות הבאים:
- אחד מהשניים:
bounds
, שהוא אובייקטgoogle.maps.LatLngBounds
שמגדיר את אזור החיפוש המלבני, אוlocation
ו-radius
; הראשון לוקח אובייקטgoogle.maps.LatLng
והשני מקבל מספר שלם פשוט, שמייצג את רדיוס העיגול במטרים. הרדיוס המקסימלי המותר הוא 50,000 מטר. לתשומת ליבך, כשהערך בשדהrankBy
הוא DISTANCE, עליך לצייןlocation
אבל לא ניתן לצייןradius
אוbounds
.
keyword
(אופציונלי) – מונח שיותאם לכל השדות הזמינים, כולל, בין היתר, שם, סוג וכתובת, וכן ביקורות של לקוחות ותוכן אחר של צד שלישי.minPriceLevel
ו-maxPriceLevel
(אופציונלי) – מגבילים את התוצאות רק למקומות שבטווח שצוין. הערכים התקינים נעים בין 0 (הכי זול) עד 4 (היקר ביותר), כולל.name
הוצא משימוש. שווה ערך ל-keyword
. הערכים בשדה הזה משולבים עם הערכים בשדהkeyword
, ומועברים כחלק מאותה מחרוזת חיפוש.openNow
(אופציונלי) - ערך בוליאני, המציין ששירות המקומות צריך להחזיר רק את המקומות שפתוחים לעסקים בזמן שליחת השאילתה. מקומות שלא מציינים את שעות הפתיחה במסד הנתונים של מקומות Google לא יוחזרו אם כוללים את הפרמטר הזה בשאילתה. להגדרה שלopenNow
לערךfalse
אין השפעה.rankBy
(אופציונלי) – מציין את הסדר שבו התוצאות יופיעו. הערכים האפשריים הם:google.maps.places.RankBy.PROMINENCE
(ברירת מחדל). כשבוחרים באפשרות הזו, התוצאות ממוינות לפי החשיבות שלהן. הדירוג ייתן עדיפות למקומות בולטים ברדיוס שהוגדר על פני מקומות קרובים שתואמים אבל בולטים פחות. מידת הבולטוּת יכולה להיות מושפעת מדירוג מקום באינדקס של Google, פופולריות גלובלית וגורמים אחרים. אם מציינים את הפרמטרgoogle.maps.places.RankBy.PROMINENCE
, הפרמטרradius
הוא חובה.google.maps.places.RankBy.DISTANCE
. באפשרות הזו, התוצאות ממוינות בסדר עולה לפי המרחק שלהן מה-location
שצוין (חובה). חשוב לשים לב שלא ניתן לצייןbounds
ו/אוradius
בהתאמה אישית אם מצייניםRankBy.DISTANCE
. כשמצייניםRankBy.DISTANCE
, חובה להגדיר אחד או יותר מהערכיםkeyword
,name
אוtype
.
type
– הגבלת התוצאות למקומות שתואמים לסוג שצוין. אפשר לציין רק סוג אחד (אם תציינו יותר מסוג אחד, המערכת תתעלם מכל הסוגים שאחרי הרשומה הראשונה). לרשימת הסוגים הנתמכים
בנוסף, צריך להעביר שיטת קריאה חוזרת אל nearbySearch()
כדי לטפל באובייקט התוצאות ובתגובה google.maps.places.PlacesServiceStatus
.
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', type: ['restaurant'] }; service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } } }
בקשות לחיפוש טקסט
שירות חיפוש הטקסט ב-Google Places הוא שירות אינטרנט שמחזיר מידע על קבוצת מקומות על סמך מחרוזת כלשהי – לדוגמה, "פיצה בתל אביב" או "חנויות נעליים ליד חיפה". בתגובה מהשירות יש רשימה של מקומות שתואמים למחרוזת הטקסט וכל הטיה של המיקום שהוגדרה. תגובת החיפוש תכלול רשימה של מקומות. אפשר לשלוח בקשה לפרטי מקום כדי לקבל מידע נוסף על כל אחד מהמקומות בתגובה.
חיפושי טקסט מתחילים באמצעות קריאה לשיטה textSearch()
של PlacesService
.
service = new google.maps.places.PlacesService(map); service.textSearch(request, callback);
השיטה הזו מקבלת בקשה עם השדות הבאים:
query
(חובה) מחרוזת הטקסט שבה רוצים לחפש, לדוגמה: "מסעדה" או "הרחוב הראשי 123". השם צריך להיות שם, כתובת או קטגוריה של מוסדות. סוגים אחרים של קלט יכולים ליצור שגיאות ולא בטוח שיחזירו תוצאות תקינות. שירות המקומות יחזיר התאמות אפשריות על סמך המחרוזת הזו, ויסדר את התוצאות לפי הרלוונטיות שלהן. הפרמטר הזה הופך לאופציונלי אם נעשה שימוש בפרמטרtype
גם בבקשת החיפוש.- אפשר גם:
openNow
- ערך בוליאני, המציין ששירות המקומות צריך להחזיר רק את המקומות שפתוחים לעסקים בזמן שליחת השאילתה. מקומות שלא מציינים את שעות הפתיחה במסד הנתונים של מקומות Google לא יוחזרו אם כוללים את הפרמטר הזה בשאילתה. להגדרה שלopenNow
לערךfalse
אין השפעה.minPriceLevel
ו-maxPriceLevel
— הצגת התוצאות רק למקומות בטווח המחיר שצוינה. הערכים החוקיים נעים בין 0 (הזול ביותר) עד 4 (היקר ביותר), כולל.- אחד מהשניים:
bounds
— אובייקטgoogle.maps.LatLngBounds
שמגדיר את המלבן שבו יש לחפש, אוlocation
ו-radius
— אפשר להטות את התוצאות במעגל מסוים על ידי העברתlocation
ופרמטרradius
. פעולה זו מורה לשירות המקומות להעדיף להציג תוצאות בתוך אותו מעגל. ייתכן שעדיין יוצגו תוצאות מחוץ לאזור המוגדר. המיקום לוקח אובייקטgoogle.maps.LatLng
, והרדיוס הוא מספר שלם פשוט שמייצג את רדיוס העיגול במטרים. הרדיוס המקסימלי המותר הוא 50 000 מטר.
type
– הגבלת התוצאות למקומות שתואמים לסוג שצוין. אפשר לציין רק סוג אחד (אם תציינו יותר מסוג אחד, המערכת תתעלם מכל הסוגים שאחרי הרשומה הראשונה). לרשימת הסוגים הנתמכים
בנוסף, צריך להעביר אל textSearch()
שיטת קריאה חוזרת (callback) כדי לטפל באובייקט התוצאות ובתגובה google.maps.places.PlacesServiceStatus
.
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', query: 'restaurant' }; service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { var place = results[i]; createMarker(results[i]); } } }
תגובות לחיפוש
קודי סטטוס
אובייקט התגובה PlacesServiceStatus
מכיל את הסטטוס של הבקשה, ויכול להיות שיש בו מידע על תוצאות ניפוי באגים שיעזרו לכם להבין למה בקשת המקום נכשלה. ערכי סטטוס אפשריים:
INVALID_REQUEST
: הבקשה הזו לא הייתה חוקית.OK
: התשובה מכילה תוצאה תקינה.OVER_QUERY_LIMIT
: דף האינטרנט חרג ממכסת הבקשות שלו.REQUEST_DENIED
: לדף האינטרנט אסור להשתמש בשירות PlacesService.UNKNOWN_ERROR
: לא ניתן היה לעבד את בקשת PlacesService עקב שגיאה בחיבור לשרת. אם מנסים שוב, הבקשה עשויה להצליח.ZERO_RESULTS
: לא נמצאה תוצאה לבקשה הזו.
תוצאות חיפוש של מקומות
הפונקציות findPlace()
, nearbySearch()
ו-textSearch()
מחזירות מערך של אובייקטים של
PlaceResult
.
כל אובייקט PlaceResult
יכול לכלול את המאפיינים הבאים:
business_status
מציין את סטטוס התפעול של המקום, אם מדובר בעסק. הערך יכול להכיל אחד מהערכים הבאים:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
לא מוחזר.formatted_address
היא מחרוזת שמכילה את הכתובת של המקום הזה בפורמט שקריא לבני אדם. המאפייןformatted_address
מוחזר רק עבור חיפוש טקסט.לעיתים קרובות כתובת זו מקבילה לכתובת למשלוח דואר. לתשומת ליבך, במדינות מסוימות, כמו בריטניה, אסור להפיץ כתובות דואר אמיתיות עקב הגבלות רישוי.
הכתובת בפורמט הנכון מורכבת באופן לוגי מרכיב כתובת אחד או יותר. לדוגמה, הכתובת "111 8th Avenue, ניו יורק, NY" כוללת את הרכיבים הבאים: "111" (מספר הרחוב), "8th Avenue" (המסלול), "New York" (העיר) ו-"NY" (מדינת ארה"ב).
אין לנתח באופן פרוגרמטי את הכתובת בפורמט הנכון. במקום זאת, צריך להשתמש ברכיבי הכתובת הנפרדים, שכלולים בתגובת ה-API בנוסף לשדה הכתובת בפורמט המתאים.
geometry
: מידע הקשור לגיאומטריה של המקום. האמצעים האלה כוללים:- ב-
location
מוצגים קווי האורך והרוחב של המקום. viewport
מגדיר את אזור התצוגה המועדף במפה כשצופים במקום הזה.
- ב-
permanently_closed
(הוצא משימוש) הוא סימון בוליאני שמציין אם המקום נסגר לצמיתות או באופן זמני (ערךtrue
). אין להשתמש ב-permanently_closed
. במקום זאת, ניתן להשתמש ב-business_status
כדי לראות את הסטטוס התפעולי של עסקים.plus_code
(ראו קוד מיקום פתוח וקודי פלוס) הוא הפניה למיקום מקודד, שנגזר מקואורדינטות של קווי אורך ורוחב, שמייצג שטח: 1/8,000 ממעלה 1/8,000 ממעלה (כ-14 מטרים בקו המשווה) או קטן יותר. אפשר להשתמש בקודי Plus כתחליף לכתובות רחובות במקומות שבהם הן לא קיימות (שבהן המבנים אינם ממוספרים או הרחובות לא נקובים).ה-Plus Code מעוצב כקוד גלובלי וכקוד מורכב:
global_code
הוא קוד אזור בן 4 תווים וקוד מקומי באורך 6 תווים או יותר (849VCWC8+R9).compound_code
הוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש (CWC8+R9, Mountain View, CA, USA). אין לנתח את התוכן הזה באופן פרוגרמטי.
html_attributions
: מערך של ייחוסים שצריך להציג בעת הצגת תוצאות החיפוש. כל רשומה במערך מכילה את טקסט ה-HTML של שיוך יחיד. הערה: זהו אוסף של כל פרטי השיוך של כל תגובה לחיפוש. לכן, כלPlaceResult
האובייקטים בתגובה מכילים רשימות שיוך זהות.icon
מחזירה את כתובת ה-URL של סמל PNG צבעוני בגודל 71px x 71px.icon_mask_base_uri
מחזירה את כתובת ה-URL הבסיסית של סמל ללא צבע, פחות התוסף .svg או .pngicon_background_color
מחזיר את קוד ברירת המחדל של צבע HEX עבור הקטגוריה של המקום.name
: שם המקום.- השדה
opening_hours
עשוי לכלול את המידע הבא:open_now
הוא ערך בוליאני שמציין אם המקום פתוח בשעה הנוכחית (הוצא משימוש בספריית המקומות, בממשק JavaScript של מפות Google. במקום זאת, יש להשתמש ב-utc_offset_minutes
).
place_id
הוא מזהה טקסט שמזהה מקום באופן ייחודי. כדי לאחזר מידע על המקום, יש להעביר את המזהה הזה בבקשה של פרטי המקום. מידע נוסף על הפניה למקום באמצעות מזהה מקוםrating
מכיל את הדירוג של המקום, מ-0.0 עד 5.0, על סמך ביקורות מצטברות של משתמשים.types
מגוון סוגים של המקום הזה (למשל:["political", "locality"]
או["restaurant", "lodging"]
). המערך הזה יכול להכיל ערכים מרובים או להיות ריק. ייתכן שיתווספו ערכים חדשים ללא הודעה מוקדמת. אפשר לראות את רשימת הסוגים הנתמכים.vicinity
: כתובת פשוטה יותר של המקום, שכוללת את שם הרחוב, מספר הרחוב והאזור, אבל לא את המחוז/המדינה, המיקוד או המדינה. לדוגמה, הערך שלvicinity
במשרדי Google באוסטרליה הוא5/48 Pirrama Road, Pyrmont
.
גישה לתוצאות נוספות
כברירת מחדל, כל חיפוש מקום מחזיר עד 20 תוצאות לכל שאילתה. עם זאת, כל חיפוש יכול להחזיר עד 60 תוצאות, בחלוקה בין שלושה דפים.
דפים נוספים זמינים דרך האובייקט PlaceSearchPagination
. כדי לגשת לדפים נוספים, צריך לתעד את האובייקט PlaceSearchPagination
באמצעות פונקציית קריאה חוזרת. ההגדרה של האובייקט PlaceSearchPagination
היא:
hasNextPage
נכס בוליאני שמציין אם יש תוצאות נוספות.true
כאשר יש דף תוצאות נוסף.nextPage()
פונקציה שתחזיר את קבוצת התוצאות הבאה. לאחר ביצוע חיפוש, עליך להמתין שתי שניות עד שדף התוצאות הבא יהיה זמין.
כדי לראות את קבוצת התוצאות הבאה, צריך להתקשר למספר nextPage
.
חובה להציג כל דף תוצאות לפני הצגת דף התוצאות הבא. חשוב לשים לב שכל חיפוש נחשב כבקשה אחת כנגד מגבלות השימוש.
הדוגמה הבאה ממחישה איך לשנות את פונקציית הקריאה החוזרת כדי לתעד את האובייקט PlaceSearchPagination
, כך שאפשר יהיה לשלוח כמה בקשות חיפוש.
TypeScript
// This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initMap(): void { // Create the map. const pyrmont = { lat: -33.866, lng: 151.196 }; const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { center: pyrmont, zoom: 17, mapId: "8d193001f940fde3", } as google.maps.MapOptions ); // Create the places service. const service = new google.maps.places.PlacesService(map); let getNextPage: () => void | false; const moreButton = document.getElementById("more") as HTMLButtonElement; moreButton.onclick = function () { moreButton.disabled = true; if (getNextPage) { getNextPage(); } }; // Perform a nearby search. service.nearbySearch( { location: pyrmont, radius: 500, type: "store" }, ( results: google.maps.places.PlaceResult[] | null, status: google.maps.places.PlacesServiceStatus, pagination: google.maps.places.PlaceSearchPagination | null ) => { if (status !== "OK" || !results) return; addPlaces(results, map); moreButton.disabled = !pagination || !pagination.hasNextPage; if (pagination && pagination.hasNextPage) { getNextPage = () => { // Note: nextPage will call the same handler function as the initial call pagination.nextPage(); }; } } ); } function addPlaces( places: google.maps.places.PlaceResult[], map: google.maps.Map ) { const placesList = document.getElementById("places") as HTMLElement; for (const place of places) { if (place.geometry && place.geometry.location) { const image = { url: place.icon!, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; new google.maps.Marker({ map, icon: image, title: place.name!, position: place.geometry.location, }); const li = document.createElement("li"); li.textContent = place.name!; placesList.appendChild(li); li.addEventListener("click", () => { map.setCenter(place.geometry!.location!); }); } } } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
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;
ניסוי לדוגמה
פרטי מקומות
בנוסף להצגת רשימה של מקומות באזור מסוים, שירות המקומות יכול גם להציג מידע מפורט על מקום ספציפי. כשמקום מוחזר בתגובה לחיפוש מקום, אפשר להשתמש במזהה המקום שלו כדי לבקש פרטים נוספים לגבי אותו מקום, למשל: הכתובת המלאה, מספר הטלפון, דירוג המשתמשים, ביקורות וכו'.
בקשות לפרטי מקום
בקשת פרטי מקום נדרשת באמצעות קריאה לשיטה 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
, {18/decat} למפות,
url
preed JavaScript, {18/de (ב-JavaScript {18/deutc_offset
utc_offset_minutes
vicinity
יצירת קשר
קטגוריית אנשי הקשר כוללת את השדות האלה:
formatted_phone_number
, international_phone_number
, opening_hours
, website
אווירה
קטגוריית 'אטמוספירה' כוללת את השדות הבאים:
price_level
, rating
, reviews
,
user_ratings_total
למידע נוסף על שדות של מקומות למידע נוסף על אופן החיוב של בקשות לנתוני מקום, תוכלו לקרוא את המאמר שימוש וחיוב.
תגובות עם פרטי המקום
קודי סטטוס
אובייקט התגובה PlacesServiceStatus
מכיל את סטטוס הבקשה, והוא עשוי להכיל מידע על תוצאות ניפוי באגים שיעזרו לך להבין למה הבקשה של פרטי המקום נכשלה. ערכי סטטוס אפשריים:
INVALID_REQUEST
: הבקשה הזו לא הייתה חוקית.OK
: התשובה מכילה תוצאה תקינה.OVER_QUERY_LIMIT
: דף האינטרנט חרג ממכסת הבקשות שלו.NOT_FOUND
המיקום שאליו יש הפניה לא נמצא במסד הנתונים של 'מקומות'.REQUEST_DENIED
: לדף האינטרנט אסור להשתמש בשירות PlacesService.UNKNOWN_ERROR
: לא ניתן היה לעבד את בקשת PlacesService עקב שגיאה בחיבור לשרת. אם מנסים שוב, הבקשה עשויה להצליח.ZERO_RESULTS
: לא נמצאה תוצאה לבקשה הזו.
תוצאות של פרטי מקומות
קריאה מוצלחת של getDetails()
מחזירה אובייקט
PlaceResult
עם המאפיינים הבאים:
address_components
: מערך שמכיל את הרכיבים הנפרדים שרלוונטיים לכתובת הזו.כל רכיב כתובת מכיל בדרך כלל את השדות הבאים:
types[]
הוא מערך שמציין את הסוג של רכיב הכתובת. אפשר לראות את רשימת הסוגים הנתמכים.long_name
הוא שם הטקסט או תיאור הטקסט המלא של רכיב הכתובת כפי שהוחזר על ידי ה-Geocoder.short_name
הוא שם טקסטואלי מקוצר של רכיב הכתובת, אם הוא זמין. לדוגמה, רכיב כתובת של מדינת אלסקה עשוי לכלולlong_name
את "אלסקה" ו-short_name
את "AK" באמצעות קיצור בן 2 האותיות.
חשוב לשים לב לעובדות הבאות לגבי המערך
address_components[]
:- מערך רכיבי הכתובת יכול להכיל יותר רכיבים מאשר הפונקציה
formatted_address
. - המערך לא כולל בהכרח את כל הישויות הפוליטיות
שמכילות כתובת, מלבד אלה שכלולות
ב-
formatted_address
. כדי לאחזר את כל הישויות הפוליטיות שמכילות כתובת ספציפית, צריך להשתמש בקידוד גיאוגרפי הפוך, ולהעביר לבקשה את קו הרוחב/קו האורך של הכתובת כפרמטר. - לא בטוח שפורמט התשובה יישאר זהה בין הבקשות. באופן ספציפי, מספר ה
address_components
משתנה בהתאם לכתובת המבוקשת, והוא עשוי להשתנות עם הזמן לגבי אותה כתובת. מיקום רכיב יכול לשנות את מיקום המערך. סוג הרכיב עשוי להשתנות. ייתכן שחסר רכיב מסוים בתגובה מאוחרת יותר.
business_status
מציין את סטטוס התפעול של המקום, אם מדובר בעסק. הערך יכול להכיל אחד מהערכים הבאים:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
לא מוחזר.formatted_address
: הכתובת של המקום הזה בפורמט שקריא לבני אדם.לעיתים קרובות כתובת זו מקבילה לכתובת למשלוח דואר. לתשומת ליבך, במדינות מסוימות, כמו בריטניה, אסור להפיץ כתובות דואר אמיתיות עקב הגבלות רישוי.
הכתובת בפורמט הנכון מורכבת באופן לוגי מרכיב כתובת אחד או יותר. לדוגמה, הכתובת "111 8th Avenue, ניו יורק, NY" כוללת את הרכיבים הבאים: "111" (מספר הרחוב), "8th Avenue" (המסלול), "New York" (העיר) ו-"NY" (מדינת ארה"ב).
אין לנתח באופן פרוגרמטי את הכתובת בפורמט הנכון. במקום זאת, צריך להשתמש ברכיבי הכתובת הנפרדים, שכלולים בתגובת ה-API בנוסף לשדה הכתובת בפורמט המתאים.
formatted_phone_number
: מספר הטלפון של המקום, בפורמט שתואם למוסכמות האזוריות של המספר.geometry
: מידע הקשור לגיאומטריה של המקום. האמצעים האלה כוללים:- ב-
location
מוצגים קווי האורך והרוחב של המקום. viewport
מגדיר את אזור התצוגה המועדף במפה כשצופים במקום הזה.
- ב-
permanently_closed
(הוצא משימוש) הוא סימון בוליאני שמציין אם המקום נסגר לצמיתות או באופן זמני (ערךtrue
). אין להשתמש ב-permanently_closed
. במקום זאת, ניתן להשתמש ב-business_status
כדי לראות את הסטטוס התפעולי של עסקים.plus_code
(ראו קוד מיקום פתוח וקודי פלוס) הוא הפניה למיקום מקודד, שנגזר מקואורדינטות של קווי אורך ורוחב, שמייצג שטח: 1/8,000 ממעלה 1/8,000 ממעלה (כ-14 מטרים בקו המשווה) או קטן יותר. אפשר להשתמש בקודי Plus כתחליף לכתובות רחובות במקומות שבהם הן לא קיימות (שבהן המבנים אינם ממוספרים או הרחובות לא נקובים).ה-Plus Code מעוצב כקוד גלובלי וכקוד מורכב:
global_code
הוא קוד אזור בן 4 תווים וקוד מקומי באורך 6 תווים או יותר (849VCWC8+R9).compound_code
הוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש (CWC8+R9, Mountain View, CA, USA). אין לנתח את התוכן הזה באופן פרוגרמטי.
html_attributions
: טקסט השיוך שיוצג עבור תוצאת המקום הזו.icon
: כתובת URL למשאב תמונה שיכול לייצג את הסוג של המקום הזה.- מספר הטלפון של המקום
international_phone_number
מופיע בפורמט לחיוג בינלאומי. הפורמט הבינלאומי כולל את קוד המדינה, ולפניו מופיע סימן הפלוס (+). לדוגמה,international_phone_number
של משרד Google בסידני שבאוסטרליה הוא+61 2 9374 4000
. name
: שם המקום.utc_offset
הוצא משימוש בספריית המקומות, בממשק ה-API של JavaScript של מפות Google, יש להשתמש ב-utc_offset_minutes
במקום זאת.utc_offset_minutes
מכיל את מספר הדקות שבהן אזור הזמן הנוכחי של המקום הזה הפרש משעון UTC. לדוגמה, עבור מקומות בסידני, אוסטרליה שבשעון קיץ, שעון 660 יהיה (+11 שעות משעון UTC), ועבור מקומות בקליפורניה שמחוץ לשעון קיץ הערך יהיה -480 (-8 שעות משעון UTC).- השדה
opening_hours
מכיל את המידע הבא:open_now
(הוצא משימוש בספריית המקומות, ב- Maps JavaScript API. במקום זאת יש להשתמש ב-opening_hours.isOpen(). בסרטון הזה מוסבר איך להשתמש ב-isOpen
עם פרטי המקום.) הוא ערך בוליאני שמציין אם המקום פתוח בשעה הנוכחית.periods[]
הוא מערך של תקופות פתיחה באורך של שבעה ימים, החל מיום ראשון, בסדר כרונולוגי. כל תקופה כוללת:- השדה
open
כולל צמד אובייקטים של יום ושעה שמתארים מתי המקום נפתח:day
מספר בין 0 ל-6, בהתאם לימים בשבוע, החל מיום ראשון. לדוגמה, 2 פירושו יום שלישי.time
עשוי להכיל את השעה ביום בפורמט של 24 שעות hhmm (הערכים נמצאים בטווח של 0000-2359).time
ידווח באזור הזמן של המקום.
close
עשוי לכלול צמד אובייקטים של יום ושעה שמתארים את שעת הסגירה של המקום. הערה: אם מקום כלשהו פתוח תמיד, הקטעclose
לא יופיע בתשובה. אפליקציות יכולות להיות מיוצגות תמיד כתקופה שלopen
, שמכילה את הערךday
עם הערך 0 ואת הערךtime
עם הערך 0000, ללאclose
.
- השדה
weekday_text
הוא מערך של שבע מחרוזות שמייצגות את שעות הפתיחה בפורמט של כל יום בשבוע. אם צוין פרמטרlanguage
בבקשה 'פרטי מקום', שירות המקומות יפורמט ויבצע לוקליזציה של שעות הפתיחה בהתאם לשפה זו. סדר הרכיבים במערך הזה תלוי בפרמטרlanguage
. חלק מהשפות מתחילות את השבוע ביום שני, ואילו אחרות מתחילות ביום ראשון.
permanently_closed
(הוצא משימוש) הוא סימון בוליאני שמציין אם המקום נסגר לצמיתות או באופן זמני (ערךtrue
). אין להשתמש ב-permanently_closed
. במקום זאת, ניתן להשתמש ב-business_status
כדי לראות את הסטטוס התפעולי של עסקים.photos[]
: מערך שלPlacePhoto
אובייקטים. אפשר להשתמש ב-PlacePhoto
כדי לקבל תמונה באמצעות השיטהgetUrl()
, או לחפש את הערכים הבאים באובייקט:height
: הגובה המקסימלי של התמונה, בפיקסלים.width
: הרוחב המקסימלי של התמונה, בפיקסלים.html_attributions
: טקסט השיוך שיוצג עם תמונת המקום הזו.
place_id
: מזהה טקסט שמזהה מקום באופן ייחודי וניתן להשתמש בו כדי לאחזר מידע על המקום באמצעות בקשה לפרטי מקום. מידע נוסף על הפניה למקום באמצעות מזהה מקוםrating
: הדירוג של המקום, מ-0.0 עד 5.0, על סמך ביקורות מצטברות של משתמשים.reviews
מערך של עד חמש ביקורות. כל ביקורת כוללת כמה רכיבים:- השדה
aspects[]
מכיל מערך שלPlaceAspectRating
אובייקטים, שכל אחד מהם מספק דירוג של מאפיין אחד של המוסד. האובייקט הראשון במערך נחשב להיבט הראשי. כלPlaceAspectRating
מוגדר כך:type
שם ההיבט שמסווג. הסוגים הנתמכים הם:appeal
,atmosphere
,decor
,facilities
,food
,overall
,quality
ו-service
.rating
הדירוג של המשתמש ביחס להיבט הספציפי הזה, מ-0 עד 3.
author_name
שם המשתמש ששלח את הביקורת. ביקורות אנונימיות ישויכו ל'משתמש Google'. אם הוגדר פרמטר של שפה, הביטוי 'משתמש ב-Google' יחזיר מחרוזת שמותאמת לשוק המקומי.author_url
כתובת ה-URL של פרופיל Google+ של המשתמש, אם הוא זמין.language
קוד שפה IETF שמציין את השפה שבה נעשה שימוש בביקורת של המשתמש. השדה הזה מכיל רק את תג השפה הראשי, ולא את התג המשני שמציין מדינה או אזור. לדוגמה, כל הביקורות באנגלית מתויגות כ-'en', ולא כ-'en-AU' או 'en-UK' וכן הלאה.rating
הדירוג הכולל של המשתמש במקום הזה. זהו מספר שלם, מ-1 עד 5.text
הביקורת של המשתמש. כשבודקים מיקום ב-Google Places, ביקורות טקסט נחשבות כאופציונליות. לכן, השדה הזה יכול להיות ריק.
- השדה
types
מגוון סוגים של המקום הזה (למשל:["political", "locality"]
או["restaurant", "lodging"]
). המערך הזה יכול להכיל ערכים מרובים או להיות ריק. ייתכן שיתווספו ערכים חדשים ללא הודעה מוקדמת. אפשר לראות את רשימת הסוגים הנתמכים.url
: כתובת ה-URL של הדף הרשמי של Google של המקום הזה. זהו הדף בבעלות Google שמכיל את המידע הזמין הטוב ביותר על המקום. אפליקציות חייבות לקשר לדף הזה או להטמיע אותו בכל מסך שמציג למשתמש תוצאות מפורטות על המקום.vicinity
: כתובת פשוטה יותר של המקום, שכוללת את שם הרחוב, מספר הרחוב והאזור, אבל לא את המחוז/המדינה, המיקוד או המדינה. לדוגמה, הערך שלvicinity
במשרדי Google באוסטרליה הוא5/48 Pirrama Road, Pyrmont
. המאפייןvicinity
מוחזר רק עבור חיפוש בקרבת מקום.- ב-
website
מופיע האתר המוסמך של המקום הזה, למשל דף הבית של עסק.
הערה: ייתכן שדירוגים רב-ממדיים לא יהיו זמינים בכל המיקומים. אם יש מעט מדי ביקורות, התגובה לפרטים תכלול דירוג מדור קודם בסולם של 0.0 עד 5.0 (אם זמין), או שלא יהיה דירוג בכלל.
הפניה למקום באמצעות מזהה מקום
מזהה מקום הוא הפניה ייחודית למקום במפות Google. מזהי המקומות זמינים ברוב המיקומים, כולל עסקים, ציוני דרך, פארקים וצמתים.
כדי להשתמש במזהה מקום באפליקציה, קודם צריך לחפש את המזהה. המזהה זמין ב-PlaceResult
בבקשות 'חיפוש מקום' או 'פרטים'.
אפשר להשתמש במזהה המקום הזה כדי לחפש את פרטי המקום.
מזהים של מקומות פטורים מההגבלות על שמירה במטמון המפורטות בסעיף 3.2.3(ב) של התנאים וההגבלות של הפלטפורמה של מפות Google. כך אפשר לשמור ערכים של מזהי מקום לשימוש במועד מאוחר יותר. לשיטות המומלצות לשמירה של מזהי מקומות, אפשר לעיין בסקירה הכללית של מזהה המקום.
var map; function initialize() { // Create a map centered in Pyrmont, Sydney (Australia). map = new google.maps.Map(document.getElementById('map'), { center: {lat: -33.8666, lng: 151.1958}, zoom: 15 }); // Search for Google's office in Australia. var request = { location: map.getCenter(), radius: '500', query: 'Google Sydney' }; var service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } // Checks that the PlacesServiceStatus is OK, and adds a marker // using the place ID and location from the PlacesService. function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { var marker = new google.maps.Marker({ map: map, place: { placeId: results[0].place_id, location: results[0].geometry.location } }); } } google.maps.event.addDomListener(window, 'load', initialize);
תמונות של המקום
התכונה 'תמונת מקום' מאפשרת להוסיף לאתר תוכן מצולם באיכות גבוהה. שירות התמונות מעניק גישה למיליוני התמונות המאוחסנות במסד הנתונים של מקומות ו-Google+ Local. כשתקבלו מידע על המקום באמצעות בקשה של 'פרטי מקום', יוחזרו קובצי עזר עם צילום של תוכן רלוונטי. הבקשות 'חיפוש בקרבת מקום' ו'חיפוש טקסט' מחזירות גם הפניה אחת של תמונה לכל מקום, לפי הצורך. באמצעות השירות של תמונות Google, תוכלו לגשת לתמונות שמוזכרות ולשנות את הגודל שלהן בהתאם לגודל אופטימלי של האפליקציה.
מערך של PlacePhoto
אובייקטים יוחזר כחלק מהאובייקט PlaceResult
עבור כל בקשה של getDetails()
, textSearch()
או nearbySearch()
נגד PlacesService
.
הערה: מספר התמונות שהוחזרו משתנה לפי הבקשה.
- חיפוש בקרבת מקום או חיפוש טקסט יחזירו אובייקט
PlacePhoto
לכל היותר. - בקשת פרטים תחזיר עד עשרה אובייקטים מסוג
PlacePhoto
.
כדי לבקש את כתובת ה-URL של התמונה המשויכת, מפעילים את השיטה PlacePhoto.getUrl()
ומעבירים אובייקט PhotoOptions
חוקי. האובייקט PhotoOptions
מאפשר לציין את הגובה והרוחב המקסימליים של התמונה. אם תציינו ערך גם ל-maxHeight
וגם ל-maxWidth
, שירות התמונות ישנה את גודל התמונה לשני הגדלים, תוך שמירה על יחס הגובה-רוחב המקורי.
קטע הקוד הבא מקבל אובייקט של מקום ומוסיף סמן למפה, אם קיימת תמונה. תמונת הסמן המוגדרת כברירת מחדל תוחלף בגרסה קטנה של התמונה.
function createPhotoMarker(place) { var photos = place.photos; if (!photos) { return; } var marker = new google.maps.Marker({ map: map, position: place.geometry.location, title: place.name, icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35}) }); }
התמונות שהוחזרו על ידי שירות התמונות מגיעות ממגוון מקומות, כולל בעלי עסקים ותמונות שמשתמשים מוסיפים. ברוב המקרים, ניתן להשתמש בתמונות ללא שיוך (Attribution) או לכלול את השיוך הנדרש כחלק מהתמונה. עם זאת, אם הרכיב photo
שמוחזר כולל ערך בשדה html_attributions
, צריך לכלול את השיוך הנוסף באפליקציה בכל מקום שבו התמונה מוצגת.