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

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

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

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

רוצים לנסות?

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

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

כל אחד מהרכיבים של 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 ובאפשרויות שלו.

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

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

   places/PLACE_ID/photos/PHOTO_RESOURCE/media

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

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