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