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

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

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

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

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

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