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

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

שירות התמונות של המקום, שהוא חלק מ-Places API, הוא ממשק API לקריאה בלבד שמאפשר להוסיף לאפליקציה תוכן עם תמונות באיכות גבוהה. השירות 'תמונות של מקום' נותן לך גישה למיליוני התמונות השמורות במסד הנתונים של מקומות Google. כשמקבלים מידע על מקום באמצעות בקשה של פרטי מקום, קובצי עזר בתמונות מוחזרים עבור תוכן מצולם רלוונטי. הבקשות 'חיפוש מקום', 'חיפוש בקרבת מקום' ו'חיפוש טקסט' גם מחזירות קובץ עזר יחיד לכל מקום, כאשר הדבר רלוונטי. באמצעות השירות 'תמונות', תוכלו לגשת לתמונות שאתם מפנים ולשנות את הגודל שלהן כך שיתאים לאפליקציה שלכם.

בקשות של מקומות לתמונות

בקשת תמונה של מקום היא כתובת 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.