שירות תמונות המקום, חלק מ-Places API, הוא ממשק API לקריאה בלבד שמאפשר להוסיף לאפליקציה תוכן עם תמונות באיכות גבוהה. שירות 'תמונות של מקומות' נותן לך גישה למיליוני תמונות שמאוחסנות במסד הנתונים של 'מקומות'. כשמקבלים מידע על מקום באמצעות בקשה של פרטי מקום, קובצי עזר עם תמונות יוחזרו לתוכן מצולם רלוונטי. הבקשות 'חיפוש מקום', 'חיפוש בקרבת מקום' ו'חיפוש טקסט' מחזירות גם הפניה אחת לתמונה לכל מקום, במקרים הרלוונטיים. באמצעות השירות 'תמונות', תוכלו לגשת לתמונות שאליהן מתייחסת התמונה ולשנות את הגודל שלה בהתאם לגודל האופטימלי לאפליקציה.
בקשות של מקומות להוספת תמונה
בקשת תמונה של מקום היא כתובת URL מסוג HTTP בצורה הבאה:
https://maps.googleapis.com/maps/api/place/photo?parameters
כדי להתחיל בקשת חיפוש, נדרשים פרמטרים מסוימים. כרגיל בכתובות URL, כל הפרמטרים מופרדים באמצעות תו האמפרסנד (&
). רשימת הפרמטרים והערכים האפשריים שלהם מפורטת בהמשך.
Required parameters
photo_reference
A string identifier that uniquely identifies a photo. Photo references are returned from either a Place Search or Place Details request.
maxheight or maxwidth
maxheight
specifies the maximum desired height, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio.maxwidth
specifies the maximum desired width, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio.Both the
maxheight
andmaxwidth
properties accept an integer between1
and1600
.You must specify either
maxheight
, ormaxwidth
, or both.
הפניות לתמונות
כל הבקשות לשירות 'תמונת מקום' חייבות לכלול photo_reference
, שמוחזר בתגובה לבקשה ל'חיפוש מקום', 'חיפוש בקרבת מקום', 'חיפוש טקסט' או 'פרטי מקום'. התגובה לבקשות האלה תכיל את השדה photos[]
אם יש במקום תוכן מצולם שקשור לנושא.
הערה: מספר התמונות שהוחזרו משתנה בהתאם לבקשה.
- בקשת חיפוש מקום, חיפוש בקרבת מקום או חיפוש טקסט מחזירה לכל היותר רכיב
photo
אחד במערך. - בקשה לפרטי מקום מחזירה עד עשרה רכיבים מסוג
photo
.
כל רכיב photo
מכיל את השדות הבאים:
photo_reference
- מחרוזת המשמשת לזיהוי התמונה כששולחים בקשה לתמונה.height
— הגובה המקסימלי של התמונה.width
- הרוחב המקסימלי של התמונה.html_attributions[]
- מכיל את כל הייחוסים הנדרשים. השדה הזה תמיד יהיה קיים, אבל יכול להיות שהוא ריק.
התמונות שהוחזרו על ידי שירות התמונות מגיעות ממגוון מיקומים, כולל בעלי עסקים ותמונות שמשתמשים מוסיפים. ברוב המקרים ניתן להשתמש בתמונות ללא ייחוס, או שהייחוס הנדרש ייכלל כחלק מהתמונה. עם זאת, אם אלמנט photo
שמוחזר כולל ערך בשדה html_attributions
, צריך לכלול את השיוך הנוסף באפליקציה בכל מקום שבו מציגים את התמונה.
הדוגמה הבאה מציגה בקשה לפרטי מקום:
curl "https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJcUElzOzMQQwRLuV30nMUEUM&key=YOUR_API_KEY"
למטה מוצגת דוגמה למערך photos[]
.
...
"photos" : [
{
"html_attributions" : [],
"height" : 853,
"width" : 1280,
"photo_reference" : "ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q"
}
...
דוגמה לתמונה של מקום
בהמשך מוצגת בקשה לדוגמה. בעקבות הבקשה, המערכת תחזיר את התמונה שאליה בוצעה הפניה ותשנה את הגודל שלה כך שהיא תהיה ברוחב של 400 פיקסלים לכל היותר.
https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q &key=YOUR_API_KEY
הוספת תשובה לתמונה
התשובה לבקשה מוצלחת של תמונה של מקום תהיה תמונה. סוג התמונה תלוי בסוג התמונה שנשלחה במקור.
אם הבקשה תחרוג מהמכסה הזמינה, השרת יחזיר סטטוס HTTP 403 ויציג את התמונה הבאה כדי לציין שחרגה מהמכסה:
אם השרת לא יכול להבין את הבקשה, הוא מחזיר את סטטוס HTTP 400, שמעיד על בקשה לא חוקית. הסיבות הנפוצות ביותר לבקשה לא חוקית כוללות:
- ההפניה לתמונה שנשלחה לא צוינה כראוי.
- הבקשה לא כללה את הפרמטרים
maxwidth
אוmaxheight
. - הערך לפרמטר
maxwidth
או לפרמטרmaxheight
הוגדר ל-null
. - פג התוקף של
photo_reference
. אם פג התוקף שלphoto_reference
, צריך לשלוח בקשה לפרטי המקום, חיפוש מקום, חיפוש בקרבת מקום או לחיפוש טקסט כדי לקבל את הערך המעודכן שלphoto_reference
.