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

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

    You must specify either maxheight, or maxwidth, or both.

תמונות עזר

כל הבקשות לשירות Place Photo חייבות לכלול את השדה 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

התשובה של Place Photo

התגובה לבקשת תמונה של מקום שהצליחה היא תמונה. סוג התמונה תלוי בסוג התמונה ששלחתם במקור.

אם הבקשה חורגת מהמכסה הזמינה, השרת מחזיר את קוד הסטטוס HTTP 403 ומציג את התמונה הבאה כדי לציין שחרגתם מהמכסה:

תמונה של חריגה מהמכסה

אם השרת לא מצליח להבין את הבקשה, הוא מחזיר את קוד הסטטוס HTTP 400, שמציין בקשה לא חוקית. אלה כמה מהסיבות הנפוצות ביותר לבקשה לא חוקית:

  • לא צוינה בצורה נכונה ההפניה לתמונה ששלחת.
  • הבקשה לא כללה את הפרמטרים maxwidth או maxheight.
  • הערך של הפרמטר maxwidth או maxheight הוגדר כ-null.
  • פג התוקף של photo_reference. אם התוקף של photo_reference יפוג, צריך לשלוח בקשה ל-פרטי המקום, ל-חיפוש מקום, ל-חיפוש בקרבת מקום או ל-חיפוש טקסט כדי לקבל את הערך המעודכן של photo_reference.