‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

מפתחים באזור הכלכלי האירופי (EEA)

מבוא

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

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

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

כדאי לנסות!

הערה: מזינים את המקום name ממערך photos של גוף התגובה של פרטי המקום (חדש) ולוחצים על Execute (הפעלה). כדי לראות את התמונה, משתמשים בערך photoUri בגוף התגובה של Place Photos (New).

בקשות של Place Photos (חדש)

בקשה של Place Photos (New) היא בקשת GET לכתובת URL בפורמט הבא:

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

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

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

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

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

שם התמונה

מחרוזת מזהה שמזהה תמונה באופן ייחודי. שמות התמונות מוחזרים מבקשה של Place Details (חדש),‏ חיפוש בסביבה (חדש) או חיפוש טקסט (חדש) במאפיין 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) צריכות לכלול שם של משאב תמונה שמוחזר בתשובה לבקשה של חיפוש בסביבה (New),‏ חיפוש טקסט (New) או Place Details (New). התשובה לבקשות האלה מכילה מערך photos[] אם יש למקום תוכן צילומי שקשור אליו.

הערה: כדי לכלול את מערך photos[] בתשובה, חשוב לכלול את photos (פרטי מקום (חדש)) או את places.photos (חיפוש בקרבת מקום (חדש) וחיפוש טקסט (חדש)) במסכת השדות של הבקשה. כל API יכול להחזיר עד 10 תמונות של מיקום מסוים.

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

‫name — מחרוזת שמכילה את שם המשאב של התמונה כשמבצעים בקשה לגבי תמונה. המחרוזת הזו היא בפורמט:
```
places/PLACE_ID/photos/PHOTO_RESOURCE
```
‫heightPx – הגובה המקסימלי של התמונה, בפיקסלים.
‫widthPx – הרוחב המקסימלי של התמונה, בפיקסלים.
‫authorAttributions[] – כל הקרדיטים הנדרשים. השדה הזה תמיד קיים, אבל יכול להיות שהוא ריק.

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

בדוגמה הבאה מוצגת בקשה של Place Details (חדש) שכוללת את 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[] בתגובה מוצגת בהמשך.

    ...
    "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 (New) היא תמונה.

קודי שגיאה

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

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

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

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

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

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

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

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

רוצה לנסות?

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

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

לוחצים על סמל ה-API בצד שמאל של הדף.
מגדירים את הפרמטר name לערך:
```
places/PLACE_ID/photos/PHOTO_RESOURCE/media
```
הערה: חשוב לוודא שמשתמשים ב-name מבקשה עדכנית של Place Details (חדש), כי יכול להיות שתוקף ה-name יפוג.
מגדירים את skipHttpRedirect ל-true כדי שהבקשה תחזיר תגובת JSON. כברירת מחדל, הבקשה מחזירה את התמונה, שלא ניתן להציג באמצעות API Explorer.
לוחצים על הכפתור Execute (הפעלה). בתיבת הדו-שיח, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.
בחלונית API Explorer, לוחצים על סמל המסך המלא כדי להרחיב את החלון של API Explorer.