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