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

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

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

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

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

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

רוצים לנסות?

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

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

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

אחזור שם של תמונה

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