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

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

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

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

באמצעות 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 ו-maxwidth מקבלים מספר שלם בין 1 ל-4800.

עליך לציין 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[] אם למקום יש תוכן מצולם קשור.

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

  • name - מחרוזת שמכילה את שם המשאב של התמונה כשמבקשים תמונה. המחרוזת הזו מופיעה בפורמט:

    places/PLACE_ID/photos/PHOTO_RESOURCE
  • heightPx – הגובה המקסימלי של התמונה, בפיקסלים.
  • widthPx – הרוחב המקסימלי של התמונה, בפיקסלים.
  • authorAttributions[] – כל הייחוסים הנדרשים. השדה הזה תמיד מופיע, אבל יכול להיות שהוא ריק.

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

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

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

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