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

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

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

API Explorer מאפשר לשלוח בקשות בזמן אמת כדי להכיר את ה-API ואת אפשרויות ה-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 וגם במאפיין רוחב מקסימלי מקבלים מספר שלם בין 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 – מחרוזת שמכילה את שם המשאב של התמונה, בזמן ששולחים בקשה לתמונה. המחרוזת הזו היא בצורה:

  places/PLACE_ID/photos/PHOTO_RESOURCE

• heightPx — הגובה המקסימלי של התמונה, בפיקסלים.
• widthPx - הרוחב המקסימלי של התמונה, בפיקסלים.
• authorAttributions[] – כל השיוך (Attribution) הנדרש. השדה הזה תמיד מוצג, אבל יכול להיות שהוא ריק.

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

זהירות: לא ניתן לשמור שם של תמונה במטמון. כמו כן, יכול להיות שיפוג התוקף של השם. חשוב לוודא שתמיד מקבלים את השם מהתגובה לבקשה אל פרטי המקום (חדש), חיפוש בקרבת מקום (חדש) או חיפוש טקסט (חדש). למידע נוסף, עיינו בהגבלות השמירה במטמון שמפורטות בסעיף 3.2.3(ב)(ללא שמירה במטמון) של התנאים וההגבלות של הפלטפורמה של מפות Google.

בדוגמה הבאה מוצגת בקשת פרטי מקום שכוללת את 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 ואת האפשרויות של API.

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

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

   places/PLACE_ID/photos/PHOTO_RESOURCE/media

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

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