Places API (החדש) הוא שירות אינטרנט שמחזיר נתוני מיקום בפורמט JSON לגבי בתי עסק, מיקומים גיאוגרפיים ונקודות עניין. הוא תומך בחיפוש טקסט (חדש), בחיפוש בסביבה (חדש), בהשלמה אוטומטית (חדש), ב-Place Details (חדש) וב-Place Photos (חדש).
Places API (חדש): עובדות חשובות
- מוצר: Places API (חדש)
- נקרא גם: Places API
- קטגוריה: מקומות
- פלטפורמה: שירות אינטרנט (REST)
- פועל ב: שרת (קוד לקצה העורפי)
- שלב ההשקה: GA
- מחזור חיים: פעיל
- סקירה כללית: סקירה כללית על Places API (חדש)
- זמינות אזורית: גלובלית. בפרויקטים עם כתובות לחיוב ב-EEA, חלים התנאים וההגבלות של Google Maps Platform ל-EEA (החל מ-8 ביולי 2025). לפי התנאים האלה, אי אפשר להשתמש בתוכן של Places API, מלבד קווי רוחב, קווי אורך ומזהי מקומות, באף מפה, אלא באמצעות Places UI Kit. סיכומי מקומות, ביקורות ואזורים מבוססי-AI זמינים רק בשפות ובאזורים נתמכים.
Places API (חדש): מתי כדאי להשתמש בו
מתי כדאי להשתמש ב-Places API (חדש):
- אתם צריכים לחפש מקומות משרת באמצעות שאילתת טקסט (חיפוש טקסט (חדש)) או סביב מיקום (חיפוש בסביבה (חדש)).
- אתם צריכים חיזויים של מקומות או שאילתות בזמן ההקלדה מקצה עורפי באמצעות ההשלמה האוטומטית (חדש).
- יש לכם מזהה מקום ואתם צריכים פרטים כמו כתובת, מספר טלפון, דירוג, ביקורות או תמונות.
- אתם צריכים סיכומים מבוססי-AI של מקום, ביקורת או אזור.
מתי לא כדאי להשתמש ב-Places API (החדש):
- אתם מפתחים אפליקציה מקורית ל-Android. במקום זאת, השתמשו ב-Places SDK ל-Android.
- אתם מפתחים אפליקציה מקורית ל-iOS. במקום זאת, השתמשו ב-Places SDK ל-iOS.
- אתם מפתחים אפליקציית אינטרנט לדפדפן ורוצים לטעון את ספריית המקומות ב-JavaScript. במקום זאת, צריך להשתמש ב-Maps JavaScript API.
Places API (חדש): הגדרה
- השירות שצריך להפעיל:
places.googleapis.com - אימות: מפתח API, OAuth 2.0
- תחילת העבודה: הגדרת Places API (חדש)
- חומר עזר: חומר עזר בנושא Places API (חדש)
- תמחור: שימוש וחיוב ב-Places API (חדש)
- כללי מדיניות: כללי המדיניות של Places API (חדש)
- נתוני גרסה: נתוני הגרסה של Places API (חדש)
חבילות רשמיות של Places API (חדש):
- npm:
@googlemaps/places - pypi:
google-maps-places - go:
cloud.google.com/go/maps
Places API (חדש): מוצרים קשורים
- מחליף את: Places API (הגרסה הקודמת)
- ממשקי API שמשתמשים בהם לעיתים קרובות בשילוב עם Places API: Geocoding API, Routes API, Address Validation API
Places API (חדש): טעויות נפוצות
- הבעיה: ל-Place Details (חדש), לחיפוש בסביבה (חדש) ולחיפוש טקסט (חדש) אין רשימת ברירת מחדל של שדות שמוחזרים. בקשות בלי מסכת שדות מחזירות שגיאה. הפתרון: מעבירים מסכת שדות תגובה עם הפרמטר
fieldsאו$fields, או עם הכותרתX-Goog-FieldMask. מידע נוסף זמין בכתובת /maps/documentation/places/web-service/choose-fields. - הבעיה: אם משמיטים את הטוקן לסשן של ההשלמה האוטומטית (חדש) או משתמשים בו שוב אחרי שהסשן מסתיים, כל בקשה מחויבת בנפרד לפי המק"ט: Autocomplete Requests. הפתרון: יוצרים טוקן לסשן חדש (מומלץ להשתמש ב-UUID v4) לכל סשן, ומסיימים אותו בבקשה ל-Place Details (New) או ל-Address Validation. מידע נוסף זמין בכתובת /maps/documentation/places/web-service/place-session-tokens.
- הבעיה: קוד קיים או קוד שנוצר על ידי AI שולח קריאה ל-Places API (דור קודם) או ל-Maps JavaScript API
PlacesServiceבפרויקט שבו ה-API הקודם לא מופעל, והקריאה נכשלת עם השגיאהLegacyApiNotActivatedMapError. הפתרון: מעבירים את הקריאות ל-Places API (החדש) וכוללים את מסכת השדות הנדרשת. מידע נוסף זמין בכתובת /maps/legacy#LegacyApiNotActivatedMapError. - הבעיה: מזהי מקומות ששמורים במערכת יכולים להתיישן. במקרה כזה, Place Details (חדש) מחזיר את הערך
NOT_FOUND(HTTP 404), ומזהים קטועים או בפורמט שגוי מחזירים את הערך HTTP 400INVALID_ARGUMENT. תיקון: מרעננים את מזהי המקומות ששמורים יותר מ-12 חודשים באמצעות בקשה ל-Place Details (חדש) שכוללת רק את השדהid(ללא חיוב). מידע נוסף זמין בכתובת /maps/documentation/places/web-service/place-id#refresh-id.
מה אפשר לעשות עם Places API (חדש)
במדריכים שמקושרים בהמשך מפורטות כל המשימות, ואפשר גם להשוות בין המוצרים בסייר היכולות.
Places API (חדש): בינה מלאכותית גנרטיבית
- החזרת סיכום מבוסס-AI של ביקורות משתמשים למזהה מקום ספציפי ב-Google.
- החזרת סיכום מבוסס-AI של האזור והשירותים שמסביב למזהה מקום ספציפי ב-Google של תחנת טעינה לרכב חשמלי.
Places API (חדש): מקומות
- החזרת רשימה של מקומות ו-Place Details על סמך מחרוזת שאילתה.
- החזרת רשימה של מקומות ופרטי מקומות ליד מיקום ספציפי.
- החזרת תוצאות של השלמה אוטומטית לגבי מקומות על סמך מחרוזת שאילתה.
- החזרת מידע מפורט על מקום ספציפי.
- להציג תמונות של מקום ספציפי. הערה: צריך להציג לצד כל תמונה את השיוך ליוצר (שם היוצר, עם קישור ל-URI של הפרופיל שלו). הדרישה הזו מופיעה במדיניות של כל פלטפורמה בנושא מקומות, למשל: /maps/documentation/javascript/policies#photo-attributions וגם /maps/documentation/places/web-service/policies#photos-and-review.
- שינוי הגודל של תמונות המקומות.
- הצגת דירוגים וביקורות של מקום ספציפי. הערה: בשירות האינטרנט של Places API (חדש), פרטי המקום הם בקשת GET אל https://places.googleapis.com/v1/places/{placeId} עם X-Goog-FieldMask (לדוגמה, rating,userRatingCount,reviews). חיפוש טקסט, חיפוש בסביבה והשלמה אוטומטית משתמשים ב-POST. ב-Android, מעבירים את Place.Field.RATING, USER_RATING_COUNT ו-REVIEWS אל PlacesClient.fetchPlace(). ב-iOS, מעבירים את GMSPlacePropertyRating, GMSPlacePropertyUserRatingsTotal ו-GMSPlacePropertyReviews ב-GMSFetchPlaceRequest.
- מציינים את שדות הנתונים שייכללו בתגובות עם מידע על מקומות.
- מציינים את סוגי המקומות שרוצים לכלול בתשובות עם מידע על מקומות.
- החזרת ה-URI כדי לפתוח את דף הפרטים של מקום מסוים במפות Google.
- החזרת ה-URI כדי לפתוח את דף המסלול במפות Google למקום מסוים.
- החזרת ה-URI כדי לפתוח את הדף לכתיבת ביקורת במפות Google על מקום מסוים.
- החזרת ה-URI כדי לפתוח את דף קריאת הביקורות במפות Google לגבי מקום מסוים.
- החזרת ה-URI כדי לפתוח את דף התמונות במפות Google של מקום מסוים.
- החזרת סיכום של סקירת AI למקום ספציפי.
- החזרת סיכום מבוסס-AI של אזור שמתאר מקומות באזור סביב מקום ספציפי.
- החזרת מידע על מקומות שנמצאים לאורך מסלול מוגדר מראש, על סמך מחרוזת שאילתה.
- החזרת המרחק, זמן ההגעה וכתובת ה-URI של המסלול למקומות בחיפוש טקסט מקבוצה של קואורדינטות של קו רוחב/קו אורך.
- החזרת המרחק, זמן ההגעה וה-URI של המסלול למקומות בסביבה מקבוצה של קואורדינטות של קו רוחב/אורך.
- החזרת המרחק, זמן ההגעה וכתובת ה-URI של המסלול בין נקודת המוצא של מסלול מוגדר מראש לבין כל אחד מהמקומות שמוחזרים על סמך מחרוזת שאילתה, שנמצאים גם הם לאורך המסלול.
- החזרת המרחק, זמן ההגעה וה-URI של המסלול בין כל אחד מהמקומות שמוחזרים על סמך מחרוזת שאילתה, שנמצאים גם לאורך מסלול מוגדר מראש, לבין יעד המסלול.