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

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

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

הפניות לתמונות

כל הבקשות לשירות 'תמונת מקום' חייבות לכלול את השדה photo_reference, שמוחזר בתגובה לבקשת חיפוש מקום, חיפוש בקרבת מקום, חיפוש טקסט או פרטי מקום. אם במקום יש תוכן מצולם קשור, התגובה לבקשות האלה תכיל את השדה photos[].

הערה: מספר התמונות שמוחזרים משתנה בהתאם לבקשה.

  • בקשה של חיפוש מקום, חיפוש בקרבת מקום או חיפוש טקסט מחזירה לכל היותר רכיב photo אחד במערך.
  • בקשה לפרטי מקום מחזירה עד עשרה רכיבי photo.

כל רכיב photo מכיל את השדות הבאים:

  • photo_reference - מחרוזת שמשמשת לזיהוי התמונה כשמבקשים תמונה.
  • height – הגובה המקסימלי של התמונה.
  • width – הרוחב המקסימלי של התמונה.
  • html_attributions[] — מכילה את כל הייחוסים הנדרשים. השדה הזה תמיד יופיע, אבל יכול להיות שהוא ריק.

התמונות שהוחזרו על ידי שירות Photos מתקבלות ממגוון מיקומים, כולל בעלי עסקים ותמונות שמשתמשים מוסיפים. ברוב המקרים אפשר להשתמש בתמונות האלה ללא ייחוס, או שהייחוס הנדרש ייכלל כחלק מהתמונה. עם זאת, אם הרכיב 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.