דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

רוצים לנסות?

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

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

בקשה לתמונה של מקום היא בקשת HTTP GET לכתובת URL בפורמט:

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

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

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

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

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

שם התמונה

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

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

maxHeightPx ו-maxWidthPx

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

צריך לציין את הערך maxHeightPx, את הערך maxWidthPx או את שניהם.

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

skipHttpRedirect

אם הערך הוא false (ברירת המחדל), מבצעים הפניה אוטומטית (redirect) מסוג 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, המערכת מתעלמת מהאפשרות הזו.

רוצה לקבל שם לתמונה?

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

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

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

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

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

    ...
    "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/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

התגובה לבקשת תמונה של מקום שהצליחה היא תמונה. סוג התמונה תלוי בסוג התמונה ששלחתם במקור.

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

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

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

נסה בעצמך!

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

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

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