התמונה של המקום (חדש) השירות הוא ממשק API לקריאה בלבד שמאפשר להוסיף תוכן מצולם לאפליקציה שלך. השירות 'תמונת מקום' נותן לגשת למיליוני התמונות שמאוחסנות במסד הנתונים של 'מקומות'.
כשמקבלים מידע על מקום באמצעות 'פרטי מקום', 'חיפוש בקרבת מקום' או בקשה לחיפוש טקסט, תוכלו גם לבקש מקורות תמונה של תוכן רלוונטי לצילום. באמצעות שירות 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[]
– כל הייחוסים הנדרשים. הזה תמיד קיים, אבל יכול להיות שהוא ריק.
התמונות שהוחזרו על ידי שירות התמונות מגיעות ממגוון מיקומים,
כולל תמונות של בעלי עסקים ותמונות שמשתמשים מוסיפים. ברוב המקרים, ההגדרות האלה
ניתן להשתמש בתמונות ללא ייחוס, או שיהיה להן את השיוך הנדרש
כחלק מהתמונה. עם זאת, אם מוחזר הרכיב 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 ובתמונה הבאה כדי לציין שהמכסה חריגה:
![תמונה של חריגה מהמכסה](https://developers.google.cn/static/maps/documentation/maps-static/images/quota.png?authuser=0000&hl=he)
אם השרת לא יכול להבין את הבקשה, הוא יחזיר 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.