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