תמונות של המקום

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

שירות תמונות המקום, חלק מ-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 and maxwidth properties accept an integer between 1 and 1600.

    You must specify either maxheight, or maxwidth, 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.