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