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

בחירת פלטפורמה: Android iOS JavaScript Web Service

השירות 'תמונות של מקומות', שהוא חלק מ-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.