תמונות של המקום (חדש)

מבוא

שירות Place Photos (New) הוא API לקריאה בלבד שמאפשר להוסיף תוכן צילומי באיכות גבוהה לאפליקציה. התכונה 'תמונות של מקומות' (חדשה) מאפשרת לכם לגשת למיליוני התמונות שמאוחסנות במסד הנתונים של המקומות.

כשמקבלים מידע על מקום באמצעות בקשה של Place Details (פרטי מקום) (חדש), Nearby Search (חיפוש בסביבה) (חדש) או Text Search (חיפוש טקסט) (חדש), אפשר גם לבקש משאבי תמונות של תוכן צילומי רלוונטי. אחרי שמשתמשים ב-Place Photos (חדש), אפשר לגשת לתמונות שאליהן מתייחסים ולשנות את הגודל של התמונה לגודל האופטימלי לאפליקציה.

‫APIs Explorer מאפשר לכם לשלוח בקשות בזמן אמת כדי להכיר את ה-API ואת האפשרויות שלו:

בקשות של תמונות של המקום (חדש)

https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

הפרמטרים הנדרשים הם:

• השדה NAME מכיל את שם המשאב של התמונה.
• ‫API_KEY מכיל את מפתח ה-API.
• ‫PARAMETERS מכיל את הפרמטר maxHeightPx, את הפרמטר maxWidthPx או את שניהם.

בהמשך מפורטת רשימה מלאה של הפרמטרים הנדרשים והאופציונליים.

פרמטרים נדרשים

שם התמונה

מחרוזת מזהה שמזהה תמונה באופן ייחודי. שמות התמונות מוחזרים מבקשה של Place Details (New),‏ Nearby Search (New) או Text Search (New) במאפיין name של כל רכיב במערך photos[].

דוגמה מופיעה במאמר איך מקבלים שם של תמונה.

‫maxHeightPx ו-maxWidthPx

מציינת את הגובה והרוחב המקסימליים המיועדים של התמונה, בפיקסלים. אם התמונה קטנה מהערכים שצוינו, התמונה המקורית תוחזר. אם התמונה גדולה יותר באחד מהממדים, היא תותאם לממד הקטן מבין השניים, בהתאם ליחס הגובה-רוחב המקורי שלה. המאפיינים maxheight ו-maxwidth מקבלים מספר שלם בין 1 ל-4,800.

חובה לציין את maxHeightPx או את maxWidthPx או את שניהם.

פרמטרים אופציונליים

skipHttpRedirect

אם הערך הוא false (ברירת מחדל), צריך לבצע הפניה אוטומטית של HTTP לתמונה כדי להחזיר את התמונה. אם true, מדלגים על ההפניה האוטומטית ומחזירים תגובת JSON שמכילה את פרטי התמונה. לדוגמה:

{
  "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media",
  "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
}

המערכת מתעלמת מהאפשרות הזו בבקשות שאינן HTTP.

איך מקבלים את השם של תמונה

כל הבקשות ל-Place Photos (New) צריכות לכלול שם של משאב תמונה שמוחזר בתשובה לבקשה של Nearby Search (New),‏ Text Search (New) או Place Details (New). התשובה לבקשות האלה מכילה מערך photos[] אם יש למקום תוכן צילומי שקשור אליו.

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

• ‫name – מחרוזת שמכילה את שם המשאב של התמונה כשמבצעים בקשה לתמונה. המחרוזת הזו היא בפורמט:

  places/PLACE_ID/photos/PHOTO_RESOURCE

• ‫heightPx – הגובה המקסימלי של התמונה, בפיקסלים.
• ‫widthPx — הרוחב המקסימלי של התמונה, בפיקסלים.
• ‫authorAttributions[] – כל הקרדיטים הנדרשים. השדה הזה תמיד קיים, אבל יכול להיות שהוא ריק.

התמונות שמוחזרות על ידי Place Photos (חדש) מגיעות ממגוון מיקומים, כולל תמונות שנוספו על ידי בעלי עסקים ותמונות שנוספו על ידי משתמשים. ברוב המקרים, אפשר להשתמש בתמונות האלה ללא ציון מקור, או שהמקור יצוין כחלק מהתמונה. עם זאת, אם רכיב photo שמוחזר כולל ערך בשדה authorAttributions, צריך לכלול את הייחוס הנוסף באפליקציה בכל מקום שבו התמונה מוצגת.

בדוגמה הבאה מוצגת בקשה של פרטי מקום (חדש) שכוללת את photos במסכת השדות, כך שהתשובה כוללת את מערך photos[] בתשובה:

curl -X GET \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,photos" \
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E

    ...
    "photos" : [
      {
        "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1",
        "widthPx": 6000,
        "heightPx": 4000,
        "authorAttributions": [
          {
            "displayName": "John Smith",
            "uri": "//maps.google.com/maps/contrib/101563",
            "photoUri": "//lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
          }
        ]
      },
    ...

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

בדוגמה הבאה של בקשה מוחזרת תמונה באמצעות המשאב name שלה, והגודל שלה משתנה כך שהגובה והרוחב שלה יהיו 400 פיקסלים לכל היותר:

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/ATKogpeivkIjQ1FT7QmbeT33nBSwqLhdPvIWHfrG1WfmgrFjeZYpS_Ls7c7rj8jejN9QGzlx4GoAH0atSvUzATDrgrZic_tTEJdeITdWL-oG3TWi5HqZoLozrjTaxoAIxmROHfV5KXVcLeTdCC6kmZExSy0CLVIG3lAPIgmvUiewNf-ZHYE4-jXYwPQpWHJgqVosvZJ6KWEgowEA-qRAzNTu9VH6BPFqHakGQ7EqBAeYOiU8Dh-xIQC8FcBJiTi0xB4tr-MYXUaF0p_AqzAhJcDE6FAgLqG1s7EsME0o36w2nDRHA-IuoISBC3SIahINE3Xwq2FzEZE6TpNTFVfgTpdPhV8CGLeqrauHn2I6ePm-2hA8-87aO7aClXKJJVzlQ1dc_JuHz6Ks07d2gglw-ZQ3ibCTF5lMtCF9O-9JHyRQXsfuXw/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

התגובה לבקשה מוצלחת של Place Photos (חדש) היא תמונה.

קודי שגיאה

בקשות ל-Place Photos (חדש) עשויות להחזיר את קודי השגיאה הבאים.

חריגה מהמכסה (403)

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

בקשה לא תקינה (404)

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

• השם של התמונה ששלחתם לא צוין בצורה נכונה.
• הבקשה לא כללה את הפרמטר maxHeightPx או את הפרמטר maxWidthPx.
• הערך של הפרמטר maxHeightPx או של הפרמטר maxWidthtPx הוגדר כ-null.
• פג התוקף של name. אם תוקף name פג, צריך לשלוח בקשה אל Place Details (New),‏ Nearby Search (New) או Text Search (New) כדי לקבל name חדש.

יותר מדי בקשות (429)

‫Google ממליצה לטעון תמונות לפי דרישה. אם תנסו להציג את כל התמונות של מקום מסוים בבת אחת, יכול להיות שהשרת יחזיר סטטוס HTTP 429, שמציין שנטענו יותר מדי תמונות בו-זמנית. אם קיבלתם את הודעת השגיאה הזו, פנו לתמיכה ובקשו להגדיל את המכסה.

רוצה לנסות?

ה-API Explorer מאפשר לכם לשלוח בקשות לדוגמה כדי להכיר את ה-API ואת האפשרויות שלו.

כדי לשלוח בקשה:

1. לוחצים על סמל ה-API api בצד שמאל של הדף.
2. מגדירים את הפרמטר name לערך:

   places/PLACE_ID/photos/PHOTO_RESOURCE/media

3. מגדירים את skipHttpRedirect ל-true כדי שהבקשה תחזיר תגובת JSON. כברירת מחדל, הבקשה מחזירה את התמונה, שלא ניתן להציג אותה באמצעות API Explorer.
4. לוחצים על הלחצן Execute (הפעלה). בתיבת הדו-שיח, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.

5. בחלונית API Explorer, בוחרים בסמל המסך המלא fullscreen כדי להרחיב את החלון של API Explorer.