‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

חיפוש טקסט (חדש)

בחירת פלטפורמה: Android iOS JavaScript Web Service

מפתחים באזור הכלכלי האירופי (EEA)

מבוא

חיפוש טקסט (חדש) מחזירה מידע על קבוצה של מקומות על סמך מחרוזת (לדוגמה, ‫"pizza in New York" או "shoe stores near Ottawa" או "123 Main Street"). השירות מגיב עם רשימת מקומות שתואמים למחרוזת הטקסט ולכל הטיה של מיקום שהוגדרה.

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

‫APIs Explorer מאפשר לכם לשלוח בקשות בזמן אמת כדי להכיר את ה-API ואת האפשרויות שלו:

כדאי לנסות!

בקשות לחיפוש טקסט (חדש)

בקשה לחיפוש טקסט (חדש) היא בקשת HTTP POST מהצורה הבאה:

https://places.googleapis.com/v1/places:searchText

מעבירים את כל הפרמטרים בגוף בקשת ה-JSON או בכותרות כחלק מבקשת ה-POST. לדוגמה:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

תשובות של חיפוש טקסט (חדש)

התכונה "חיפוש טקסט (חדש)" מחזירה אובייקט JSON כתגובה. בתשובה:

המערך places מכיל את כל המקומות התואמים.
כל מקום במערך מיוצג על ידי אובייקט Place. אובייקט Place שמכיל מידע מפורט על מקום יחיד.
ה-FieldMask שמועבר בבקשה מציין את רשימת השדות שמוחזרים באובייקט Place.
אין ערובה לכך שרשימת המקומות שמוחזרת תהיה עקבית לבקשות זהות.

אובייקט ה-JSON המלא הוא בפורמט הבא:

{
  "places": [
    {
      object (Place)
    }
  ]
}

פרמטרים נדרשים

FieldMask

כדי לציין את רשימת השדות שיוחזרו בתשובה, יוצרים מסכת שדות של תשובה. מעבירים את מסכת שדות התגובה לשיטה באמצעות פרמטר של כתובת URL‏ $fields או fields, או באמצעות כותרת ה-HTTP‏ X-Goog-FieldMask. אין רשימת ברירת מחדל של שדות שמוחזרים בתשובה. אם לא מציינים את מסכת השדה, הפונקציה מחזירה שגיאה.

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

צריך לציין רשימה מופרדת בפסיקים של סוגי נתוני המקומות שרוצים לקבל. לדוגמה, כדי לאחזר את השם המוצג ואת הכתובת של המקום.
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
הערה: אסור להוסיף רווחים בשום מקום ברשימת השדות.

אפשר להשתמש ב-* כדי לאחזר את כל השדות.
```
X-Goog-FieldMask: *
```
אמנם אפשר להשתמש בתו הכללי (*) בפיתוח, אבל Google לא ממליצה להשתמש במסכת שדות התגובה של התו הכללי בסביבת ייצור, כי אפשר לקבל כמות גדולה של נתונים.

הנחיות נוספות לשימוש ב-places.iconMaskBaseUri וב-places.iconBackgroundColor מפורטות בקטע סמלי מקומות.

מציינים אחד או יותר מהשדות הבאים:
- השדות הבאים מפעילים את המק"ט "חיפוש טקסט – גרסה בסיסית – מזהה בלבד":
  places.attributions
  places.id
  places.consumerAlert
  places.name^*
  nextPageToken
  places.movedPlace
  places.movedPlaceId
  ‫^* השדה places.name מכיל את שם המשאב של המקום בפורמט: places/PLACE_ID. כדי לגשת לשם הטקסט של המקום, משתמשים ב-places.displayName במק"ט Pro.
  
  הרשימה המלאה של השדות והמקט"ים שמשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).
- השדות הבאים מפעילים את מק"ט חיפוש טקסט Pro:
  places.accessibilityOptions
  places.addressComponents
  places.addressDescriptor^*
  places.adrFormatAddress
  places.businessStatus
  places.containingPlaces
  places.displayName
  places.formattedAddress
  places.googleMapsLinks
  places.googleMapsTypeLabel
  places.googleMapsUri
  places.iconBackgroundColor
  places.iconMaskBaseUri
  places.location
  places.openingDate
  places.photos
  places.plusCode
  places.postalAddress
  places.primaryType
  places.primaryTypeDisplayName
  places.pureServiceAreaBusiness
  places.shortFormattedAddress
  places.searchUri
  places.subDestinations
  places.timeZone
  places.types
  places.utcOffsetMinutes
  places.viewport
  
  ^* תיאורי כתובות זמינים לכלל המשתמשים בהודו, ובמקומות אחרים הם זמינים כניסוי.
  רשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).
- השדות הבאים מפעילים את מק"ט חיפוש טקסט Enterprise:
  places.currentOpeningHours
  places.currentSecondaryOpeningHours
  places.internationalPhoneNumber
  places.nationalPhoneNumber
  places.priceLevel
  places.priceRange
  places.rating
  places.regularOpeningHours
  places.regularSecondaryOpeningHours
  places.transitStation
  places.userRatingCount
  places.websiteUri
  הרשימה המלאה של השדות והמקט"ים שמשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).
- השדות הבאים מפעילים את מק"ט חיפוש טקסט Enterprise + Atmosphere:
  places.allowsDogs
  places.curbsidePickup
  places.delivery
  places.dineIn
  places.editorialSummary
  places.evChargeAmenitySummary
  places.evChargeOptions
  places.fuelOptions
  places.generativeSummary
  places.goodForChildren
  places.goodForGroups
  places.goodForWatchingSports
  places.liveMusic
  places.menuForChildren
  places.neighborhoodSummary
  places.parkingOptions
  places.paymentOptions
  places.outdoorSeating
  places.reservable
  places.restroom
  places.reviews
  places.reviewSummary
  routingSummaries^*
  places.servesBeer
  places.servesBreakfast
  places.servesBrunch
  places.servesCocktails
  places.servesCoffee
  places.servesDessert
  places.servesDinner
  places.servesLunch
  places.servesVegetarianFood
  places.servesWine
  places.takeout
  
  ^* חיפוש טקסט וחיפוש בסביבה בלבד
  רשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

textQuery

מחרוזת הטקסט שבה יתבצע החיפוש. לדוגמה, "מסעדה", "רחוב הרצל 123" או "המקום הכי טוב לבקר בו בתל אביב". ה-API מחזיר התאמות אפשריות על סמך המחרוזת הזו ומסדר את התוצאות לפי מידת הרלוונטיות שלהן.

התכונה 'חיפוש טקסט' (חדשה) לא מיועדת לשאילתות דו-משמעיות, כולל:

סוג השאילתה	דוגמה
יותר מדי מושגים או אילוצים, כמו שמות של כמה מקומות, כבישים או ערים בשאילתה אחת	"Market Street San Francisco San Jose Airport"
רכיבים של כתובת למשלוח דואר שלא מיוצגים במפות Google	"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco"
שמות של עסקים, רשתות או קטגוריות בשילוב עם מיקומים שבהם הישויות האלה לא זמינות	"Tesco near Dallas, Texas"
שאילתות דו-משמעיות עם כמה פרשנויות	"Charger drop-off"
שמות היסטוריים שכבר לא נמצאים בשימוש	"Middlesex United Kingdom"
רכיבים או כוונות שאינם גיאוגרפיים	"כמה סירות יש בנמל ונטורה?"
שמות לא רשמיים או שמות מותאמים אישית	"The Jenga" "The Helter Skelter"
קואורדינטות של אורך ורוחב	‎"37.422131,-122.084801"

פרמטרים אופציונליים

includeFutureOpeningBusinesses

אם true, הפונקציה מחזירה עסקים שצפויים להיפתח בעתיד. ברירת המחדל היא false.

כדי לאחזר את סטטוס העסק, צריך לכלול את places.businessStatus במסכת השדות של הבקשה. כדי לאחזר את תאריך הפתיחה הצפוי של העסק, צריך לכלול את places.openingDate במסכת השדות של הבקשה.
includedType

הטיית התוצאות למקומות שתואמים לסוג שצוין, כפי שמוגדר בטבלה א'. אפשר לציין רק סוג אחד. לדוגמה:
- "includedType":"bar"
- "includedType":"pharmacy"
הערה: הערכים בטבלה ב' מוחזרים רק בתגובה. אי אפשר להשתמש בערכים בטבלה ב' כמסנן.

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

כדי להחיל סינון לפי סוג על כל השאילתות, מגדירים את strictTypeFiltering לערך true.

הפרמטר הזה לא חל על שאילתות לגבי בתי מלון או על שאילתות גיאופוליטיות (לדוגמה, שאילתות שקשורות לאזורים מנהליים, לרשויות מוניציפאליות, למיקודים, למחוזות במערכת החינוך או למדינות).
includePureServiceAreaBusinesses

אם הערך הוא true, התגובה כוללת עסקים שמגיעים אל הלקוחות או מציעים להם משלוחים, אבל אין להם מיקום פיזי. אם הערך מוגדר ל-false, ה-API מחזיר רק עסקים עם מיקום פיזי.
languageCode

השפה שבה התוצאות יוחזרו.
- כאן אפשר לעיין ברשימת השפות הנתמכות. ‫Google מעדכנת את השפות הנתמכות לעיתים קרובות, לכן יכול להיות שהרשימה הזו לא מלאה.
- אם לא מציינים את הערך languageCode, ברירת המחדל של ה-API היא en. אם תציינו קוד שפה לא חוקי, ה-API יחזיר שגיאת INVALID_ARGUMENT.
- ה-API מנסה לספק כתובת רחוב שקריאה גם למשתמש וגם למקומיים. כדי להשיג את המטרה הזו, הוא מחזיר כתובות רחוב בשפה המקומית, בתעתיק לכתב שניתן לקריאה על ידי המשתמש אם יש צורך, בהתאם לשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מהרכיב הראשון.
- אם השם לא זמין בשפה המועדפת, ה-API ישתמש בהתאמה הכי קרובה.
- לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שה-API בוחר להחזיר, ועל הסדר שבו הן מוחזרות. כלי להמרת כתובות לקואורדינטות (geocoder) מפרש קיצורים בצורה שונה בהתאם לשפה, כמו קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת.
locationBias

מציין אזור לחיפוש. המיקום הזה משמש כהטיה, כלומר יכול להיות שיוחזרו תוצאות שמסביב למיקום שצוין, כולל תוצאות מחוץ לאזור שצוין.

אפשר לציין את locationRestriction או את locationBias, אבל לא את שניהם. אפשר לחשוב על locationRestriction כציון של האזור שבו התוצאות חייבות להיות, ועל locationBias כציון של האזור שבו התוצאות כנראה יהיו בתוכו או בקרבתו, אבל יכולות להיות מחוץ לאזור.

הערה: אם לא מציינים את הערכים locationBias ו-locationRestriction, ה-API משתמש בהטיה לפי כתובת IP כברירת מחדל. כשמשתמשים בהטיה לפי כתובת IP, ה-API משתמש בכתובת ה-IP של המכשיר כדי להטות את התוצאות.

הערה: אפשר לבטל את הפרמטר locationBias אם הפרמטר textQuery מכיל מיקום מפורש כמו Market in Barcelona. במקרה כזה, המערכת מתעלמת מהמדיניות locationBias.

מציינים את האזור כאזור תצוגה מלבני או כעיגול.
- מעגל מוגדר על ידי נקודת מרכז ורדיוס במטרים. הרדיוס חייב להיות בין 0.0 ל-50000.0, כולל. רדיוס ברירת המחדל הוא 0.0. לדוגמה:
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```
- מלבן הוא אזור תצוגה של קו רוחב וקו אורך, שמיוצג כשתי נקודות נמוכות וגבוהות מנוגדות באלכסון. הנקודה הנמוכה מסמנת את הפינה הדרום-מערבית של המלבן, והנקודה הגבוהה מייצגת את הפינה הצפון-מזרחית של המלבן.
  
  אזור התצוגה נחשב לאזור סגור, כלומר הוא כולל את הגבול שלו. הגבולות של קו הרוחב צריכים להיות בין ‎-90 ל-90 מעלות, כולל, והגבולות של קו האורך צריכים להיות בין ‎-180 ל-180 מעלות, כולל:
  - אם low = high, אזור התצוגה מורכב מהנקודה היחידה הזו.
  - אם low.longitude > high.longitude, טווח קווי האורך הפוך (אזור התצוגה חוצה את קו האורך של 180 מעלות).
  - אם low.longitude = ‎-180 מעלות ו-high.longitude = 180 מעלות, אזור הצפייה כולל את כל קווי האורך.
  - אם low.longitude = 180 מעלות ו-high.longitude = ‎-180 מעלות, טווח קווי האורך ריק.
  - אם low.latitude > high.latitude, טווח קווי הרוחב ריק.
  חובה לאכלס את הערכים הנמוכים והגבוהים, והתיבה המיוצגת לא יכולה להיות ריקה. אם אזור התצוגה ריק, תופיע שגיאה.
  
  לדוגמה, אזור התצוגה הזה כולל את כל העיר ניו יורק:
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
locationRestriction

מציינת אזור לחיפוש שאילתות קטגוריות בלבד, שיכולות להחזיר כמה מקומות (לדוגמה, "Restaurants in New York" או "Shopping malls"). לא מוחזרות תוצאות מחוץ לאזור שצוין.

מציינים את האזור כאזור תצוגה מלבני. דוגמה להגדרת אזור התצוגה מופיעה בתיאור של locationBias.

אפשר לציין locationRestriction או locationBias, אבל לא את שניהם. אפשר לחשוב על locationRestriction כהגדרת האזור שבו התוצאות חייבות להיות, ועל locationBias כהגדרת האזור שבו התוצאות כנראה יהיו, אבל הן יכולות להיות גם מחוץ לאזור.

הערה: אם משמיטים גם את locationBias וגם את locationRestriction, ה-API משתמש בהטיית IP כברירת מחדל. כשמשתמשים בהטיה לפי כתובת IP, ה-API משתמש בכתובת ה-IP של המכשיר כדי להטות את התוצאות.
maxResultCount (הוצא משימוש)

הוצא משימוש: השדה הזה הוצא משימוש לטובת pageSize. אם מציינים גם את maxResultCount וגם את pageSize, המערכת תשתמש ב-pageSize ותתעלם מ-maxResultCount.

מציין את מספר התוצאות (בין 1 ל-20) שיוצגו בכל דף. לדוגמה, אם מגדירים את הערך של maxResultCount ל-5, יוחזרו עד 5 תוצאות בדף הראשון. אם יש עוד תוצאות שאפשר להחזיר מהשאילתה, התשובה כוללת nextPageToken שאפשר להעביר לבקשה הבאה כדי לגשת לדף הבא.

הערה: אם הערך של maxResultCount הוא 0 או לא מצוין, ה-API יחזיר כברירת מחדל 20 תוצאות לכל דף. אם הערך של maxResultCount גדול מ-20, ה-API יחזיר עד 20 תוצאות לכל דף.
evOptions

מציינים פרמטרים לזיהוי של מתקני טעינה זמינים לרכב חשמלי (EV) ושל קצבי טעינה.
- connectorTypes
  
  סינון לפי סוג המחבר לטעינת רכב חשמלי שזמין במקום. מקומות שלא תומכים באף אחד מסוגי המחברים יסוננו. סוגי מחברי הטעינה לרכבים חשמליים שנתמכים כוללים מטענים משולבים (AC ו-DC), מטענים של Tesla, מטענים שתואמים לתקן GB/T (לטעינה מהירה של רכבים חשמליים בסין) ומטענים לשקע חשמל. מידע נוסף מופיע במאמרי העזרה.
  - כדי לסנן את התוצאות לפי מחבר ספציפי נתמך, מגדירים את connectorTypes לערך הזה. לדוגמה, כדי למצוא מחברים מסוג J1772 type 1, מגדירים את connectorTypes לערך EV_CONNECTOR_TYPE_J1772.
  - כדי לסנן תוצאות של מחברים לא נתמכים, מגדירים את connectorTypes כ-EV_CONNECTOR_TYPE_OTHER.
  - כדי לסנן תוצאות של כל סוג מחבר שהוא שקע חשמל, מגדירים את connectorTypes לערך EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET.
  - כדי לסנן את התוצאות לפי סוג מחבר כלשהו, צריך להגדיר את connectorTypes ל-EV_CONNECTOR_TYPE_UNSPECIFIED או לא להגדיר ערך ל-connectorTypes.
- minimumChargingRateKw
  
  מסננים מקומות לפי קצב טעינה מינימלי של מטען לרכב חשמלי בקילוואט (kW). מקומות שבהם שיעור הטעינה נמוך משיעור הטעינה המינימלי מסוננים. לדוגמה, כדי למצוא מטענים לרכב חשמלי עם מהירויות טעינה של 10 קילוואט לפחות, אפשר להגדיר את הפרמטר הזה לערך '10'.
minRating

הגבלת התוצאות רק לאלה שדירוג המשתמשים הממוצע שלהן גדול מהמגבלה הזו או שווה לה. הערכים צריכים להיות בין 0.0 ל-5.0 (כולל), במרווחים של 0.5. לדוגמה: 0, 0.5, 1.0, ... , 5.0 כולל. הערכים מעוגלים כלפי מעלה ל-0.5 הקרוב ביותר. לדוגמה, ערך של 0.6 יסנן את כל התוצאות עם דירוג נמוך מ-1.0.

הפרמטר הזה לא חל על שאילתות לגבי בתי מלון או על שאילתות גיאופוליטיות (לדוגמה, שאילתות שקשורות לאזורים מנהליים, לרשויות מוניציפאליות, למיקודים, למחוזות במערכת החינוך או למדינות).
openNow

אם true, מחזירה רק את המקומות שפתוחים לעסקים בזמן שליחת השאילתה. אם false, מחזירים את כל העסקים ללא קשר לסטטוס הפתיחה. מקומות שלא מצוינות בהם שעות פתיחה במסד הנתונים של Google Places מוחזרים אם מגדירים את הפרמטר הזה לערך false.

הפרמטר הזה לא חל על שאילתות לגבי בתי מלון או על שאילתות גיאופוליטיות (לדוגמה, שאילתות שקשורות לאזורים מנהליים, לרשויות מוניציפאליות, למיקודים, למחוזות במערכת החינוך או למדינות).
pageSize

מציין את מספר התוצאות (בין 1 ל-20) שיוצגו בכל דף. לדוגמה, אם מגדירים ערך של 5 לפרמטר pageSize, יוחזרו עד 5 תוצאות בדף הראשון. אם יש עוד תוצאות שאפשר להחזיר מהשאילתה, התשובה כוללת nextPageToken שאפשר להעביר לבקשה הבאה כדי לגשת לדף הבא.

הערה: אם הערך של pageSize הוא 0 או לא צוין, ה-API יחזיר 20 תוצאות לכל דף כברירת מחדל. אם הערך של pageSize גדול מ-20, ה-API יחזיר עד 20 תוצאות לכל דף.
pageToken

מציין את nextPageToken מגוף התגובה של הדף הקודם.
priceLevels

הגבלת החיפוש למקומות שמסומנים ברמות מחיר מסוימות. ברירת המחדל היא בחירה של כל רמות המחירים.

אפשר לצפות לרמות מחירים במקומות מהסוגים הבאים:
מקומות מסוגים שלא נתמכים לא ייכללו בתשובה אם צוין priceLevels.

מציינים מערך של ערך אחד או יותר שמוגדרים על ידי PriceLevel.

לדוגמה:
```
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
```
הערה: אסור להשתמש ב-PRICE_LEVEL_FREE בבקשה. הוא משמש רק כדי לאכלס את התשובה.

הפרמטר הזה לא חל על שאילתות לגבי בתי מלון או על שאילתות גיאופוליטיות (לדוגמה, שאילתות שקשורות לאזורים מנהליים, לרשויות מוניציפאליות, למיקודים, למחוזות במערכת החינוך או למדינות).
rankPreference

מציין איך התוצאות מדורגות בתגובה, בהתאם לסוג השאילתה:
- בשביל שאילתה קטגורית כמו 'מסעדות בניו יורק', ההגדרה שמוגדרת כברירת מחדל היא RELEVANCE (דירוג התוצאות לפי רלוונטיות לחיפוש). אפשר להגדיר את rankPreference ל-RELEVANCE או ל-DISTANCE (דירוג התוצאות לפי מרחק).
- לשאילתה לא קטגורית כמו 'Mountain View, CA', מומלץ להשאיר את rankPreference ללא הגדרה.
הפרמטר הזה לא חל על שאילתות לגבי מלונות או על שאילתות גיאופוליטיות (לדוגמה, שאילתות שקשורות לאזורים אדמיניסטרטיביים, ליישובים, למיקודים, למחוזות במערכת החינוך או למדינות).
regionCode

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

אם שם המדינה בשדה formattedAddress בתשובה זהה לערך regionCode, קוד המדינה מושמט מהשדה formattedAddress. לפרמטר הזה אין השפעה על adrFormatAddress, שתמיד כולל את שם המדינה אם הוא זמין, או על shortFormattedAddress, שאף פעם לא כולל אותו.

רוב הקודים במאגר CLDR זהים לקודים בתקן ISO 3166-1, אבל יש כמה יוצאים מן הכלל. לדוגמה, ה-ccTLD של בריטניה הוא uk (‎.co.uk), אבל קוד ISO 3166-1 שלה הוא gb (טכנית, עבור הישות 'בריטניה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.
strictTypeFiltering

משמש עם הפרמטר includedType. אם מגדירים את הערך true, המערכת מחזירה רק מקומות שתואמים לסוגים שצוינו במאפיין includedType. אם הערך הוא false (ברירת המחדל), התשובה יכולה להכיל מקומות שלא תואמים לסוגים שצוינו.

דוגמאות לחיפוש טקסט (חדש)

חיפוש מקום לפי מחרוזת שאילתה

הדוגמה הבאה מציגה בקשת חיפוש טקסט (חדש) של 'אוכל צמחוני חריף בסידני, אוסטרליה':

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

שימו לב שהכותרת X-Goog-FieldMask מציינת שהתגובה מכילה את שדות הנתונים הבאים: places.displayName,places.formattedAddress. התשובה תהיה בפורמט הבא:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
    ...
  ]
}

כדי להחזיר מידע נוסף, מוסיפים עוד סוגי נתונים למסכת השדות. לדוגמה, מוסיפים places.types,places.websiteUri כדי לכלול את סוג המסעדה ואת כתובת האינטרנט בתשובה:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri' \
'https://places.googleapis.com/v1/places:searchText'

התשובה תהיה בפורמט הבא:

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

סינון מקומות לפי רמת מחיר

משתמשים באפשרות priceLevel כדי לסנן את התוצאות למסעדות שמוגדרות כזולות או במחיר בינוני:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

בדוגמה הזו נעשה שימוש גם בכותרת X-Goog-FieldMask כדי להוסיף את שדה הנתונים places.priceLevel אל התגובה, כך שהיא תהיה בפורמט:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St, Newtown NSW 2042, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

אפשר להוסיף אפשרויות נוספות כדי לצמצם את החיפוש, כמו includedType, minRating, ‏ rankPreference, ‏ openNow, ופרמטרים אחרים שמתוארים במאמר בנושא פרמטרים אופציונליים.

הגבלת החיפוש לאזור מסוים

כדי לצמצם את החיפוש לאזור מסוים, משתמשים ב-locationRestriction או ב-locationBias, אבל לא בשניהם. אפשר לחשוב על locationRestriction כציון האזור שבו התוצאות צריכות להיות, ועל locationBias כציון האזור שבו התוצאות צריכות להיות קרובות, אבל הן יכולות להיות מחוץ לאזור.

הערה: כשמשתמשים ב-locationRestriction, אפשר לציין את האזור רק כחלון תצוגה מלבני. כשמשתמשים ב-locationBias, אפשר לציין את האזור כתיבת תצוגה מלבנית או כעיגול.

הגבלת האזור באמצעות locationRestriction

כדי להגביל את תוצאות השאילתה לאזור מסוים, משתמשים בפרמטר locationRestriction. בגוף הבקשה, מציינים את ערכי קווי הרוחב והאורך low ו-high שמגדירים את גבולות האזור.

בדוגמה הבאה מוצגת בקשה לחיפוש טקסט (חדש) של 'אוכל צמחוני' בניו יורק. הבקשה הזו מחזירה רק את 10 התוצאות הראשונות של מקומות פתוחים.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "pageSize" : "10",
  "locationRestriction": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }
}' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: API_KEY' \
  -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
  'https://places.googleapis.com/v1/places:searchText'

הטיה לאזור באמצעות locationBias

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

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "openNow": true,
  "pageSize": 10,
  "locationBias": {
    "circle": {
      "center": {"latitude": 37.7937, "longitude": -122.3965},
      "radius": 500.0
    }
  },
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

חיפוש מטענים לרכב חשמלי עם קצב טעינה מינימלי

אפשר להשתמש ב-minimumChargingRateKw וב-connectorTypes כדי לחפש מקומות עם מטענים זמינים שתואמים לרכב החשמלי שלכם.

בדוגמה הבאה מוצגת בקשה למחברי טעינה של רכב חשמלי מסוג Tesla ו-J1772 type 1 עם קצב טעינה מינימלי של 10 קילוואט במאונטיין ויו, קליפורניה. רק ארבע תוצאות מוחזרות.

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "pageSize": 4,
    "evOptions": {
      "minimumChargingRateKw": 10,
      "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
    }
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'

התגובה לבקשה תהיה:

{
  "places": [
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 16,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 100,
            "count": 8,
            "availableCount": 5,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 2,
            "availableCount": 2,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 6,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 6,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 4,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 2,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 5,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_J1772",
            "maxChargeRateKw": 3.5999999046325684,
            "count": 1,
            "availableCount": 0,
            "outOfServiceCount": 1,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "Electric Vehicle Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 10,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_OTHER",
            "maxChargeRateKw": 210,
            "count": 10
          }
        ]
      }
    }
  ]
}

חיפוש נותני שירות באזור מוגדר (SAB)

משתמשים בפרמטר includePureServiceAreaBusinesses כדי לחפש עסקים ללא כתובת פיזית (למשל, שירות ניקיון נייד או משאית אוכל).

בדוגמה הבאה מוצגת בקשה לשרברבים בסן פרנסיסקו:

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

בתשובה, עסקים ללא כתובת פיזית למתן שירות לא כוללים את השדה formattedAddress:

{
  "places": [
    {
      "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA",
      "displayName": {
        "text": "Advanced Plumbing & Drain",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Magic Plumbing Heating & Cooling",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Cabrillo Plumbing, Heating & Air",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Mr. Rooter Plumbing of San Francisco",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Pipeline Plumbing",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA",
      "displayName": {
        "text": "One Source Plumbing and Rooter",
        "languageCode": "en"
      }
    },
    /.../
  ]
}

ציון מספר התוצאות שיוחזרו בכל דף

משתמשים בפרמטר pageSize כדי לציין את מספר התוצאות שיוחזרו בכל דף. הפרמטר nextPageToken בגוף התגובה מספק אסימון שאפשר להשתמש בו בקריאות הבאות כדי לגשת לדף התוצאות הבא.

בדוגמה הבאה מוצגת בקשה לחיפוש 'פיצה בניו יורק' עם הגבלה של 5 תוצאות בכל דף:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJifIePKtZwokRVZ-UdRGkZzs"
    },
    {
      "id": "ChIJPxPd_P1YwokRfzLhSiACEoU"
    },
    {
      "id": "ChIJrXXKn5NZwokR78g0ipCnY60"
    },
    {
      "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE"
    },
    {
      "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw"
    }
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

כדי לגשת לדף הבא של התוצאות, משתמשים ב-pageToken כדי להעביר את nextPageToken בגוף הבקשה:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5,
  "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw"
    },
    {
      "id": "ChIJjaD94kFZwokR-20CXqlpy_4"
    },
    {
      "id": "ChIJ6ffdpJNZwokRmcafdROM5q0"
    },
    {
      "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM"
    },
    {
      "id": "ChIJ8164qwFZwokRhplkmhvq1uE"
    }
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

קבלת תיאורים של כתובות

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

בדוגמה הבאה מוצגת בקשה לחיפוש טקסט (חדש) של מקומות ליד קניון בסן חוזה. בדוגמה הזו, כוללים את addressDescriptors במסכת השדות:

curl -X POST -d '{
  "textQuery": "clothes",
  "maxResultCount": 5,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      }
    }
  },
  "rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchText

התשובה כוללת את המקום שצוין בבקשה, רשימה של ציוני דרך בקרבת מקום והמרחק שלהם מהמקום, ורשימה של אזורים והקשר שלהם למקום:

  {
  "places": [
    {
      "displayName": {
        "text": "Urban Outfitters",
        "languageCode": "en"
      },
      "addressDescriptor": {
        "landmarks": [
          {
            "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "food",
              "movie_theater",
              "point_of_interest",
              "restaurant",
              "shoe_store",
              "shopping_mall",
              "store"
            ],
            "spatialRelationship": "WITHIN",
            "straightLineDistanceMeters": 133.72855
          },
          {
            "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "displayName": {
              "text": "Nordstrom",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 250.99161
          },
          {
            "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "placeId": "ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "displayName": {
              "text": "Macy's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "store"
            ],
            "straightLineDistanceMeters": 116.24196
          },
          {
            "name": "places/ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "placeId": "ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "displayName": {
              "text": "Bank of America Financial Center",
              "languageCode": "en"
            },
            "types": [
              "bank",
              "establishment",
              "finance",
              "point_of_interest"
            ],
            "straightLineDistanceMeters": 121.61515
          },
          {
            "name": "places/ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "placeId": "ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "displayName": {
              "text": "Bloomingdale's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "furniture_store",
              "home_goods_store",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 81.32396
          }
        ],
        "areas": [
          {
            "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "displayName": {
              "text": "Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "displayName": {
              "text": "Central San Jose",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          }
        ]
      }
    },
    /.../
  ]
}

חיפוש עסקים שייפתחו בעתיד

בדוגמה הבאה מוצגת בקשה לחיפוש טקסט (חדש) של עסקים שייפתחו בעתיד בניו מדוז, איידהו:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.openingDate" \
-d '{
  "textQuery": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "maxResultCount": 20,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:searchText"

התגובה כוללת עסקים שייפתחו בעתיד, יחד עם הסטטוס של העסק ותאריך הפתיחה הצפוי:

{
  "places": [
    {
      "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
      "businessStatus": "FUTURE_OPENING",
      "displayName": {
        "text": "Roberts Greenhouse and Tree Farm",
        "languageCode": "en"
      },
      "openingDate": {
        "year": 2026,
        "month": 4,
        "day": 15
      }
    }
  ]
}

קבלת מידע על תחנות של תחבורה ציבורית

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

בדוגמה הבאה מוצגת בקשה לחיפוש תחנת Grand Central:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.transitStation" \
-d '{
  "textQuery": "Grand Central Station"
}' \
"https://places.googleapis.com/v1/places:searchText"

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

{
  "places": [
    {
      "id": "ChIJhRwB-yFawokRi0AhGH87UTc",
      "displayName": {
        "text": "Grand Central",
        "languageCode": "en"
      },
      "transitStation": {
        "displayName": {
          "text": "Grand Central",
          "languageCode": "en"
        },
        "agencies": [
          {
            "displayName": {
              "text": "Metro-North Railroad",
              "languageCode": "en"
            },
            "url": "http://www.mta.info/mnr",
            "lines": [
              {
                "id": "ChIJOXpD29y2wokRryDO0CocwK0",
                "vehicleType": "HEAVY_RAIL",
                "displayName": {
                  "text": "Harlem",
                  "languageCode": "en"
                },
                "textColor": "#FFFFFF",
                "backgroundColor": "#0061AA",
                "vehicleIcon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg"
                },
                "alerts": [
                  {
                    "effect": "OTHER",
                    "texts": [
                      {
                        "headline": {
                          "text": "Information",
                          "languageCode": "en"
                        },
                        "summary": {
                          "text": "Temporary platforms are in place at Botanical Garden, Williams Bridge, and Woodlawn for northbound travel. Build in extra travel time to reach the platform.",
                          "languageCode": "en"
                        },
                        "fullDescription": {
                          "text": "What's Happening? We are renovating some Harlem Line stations in the Bronx. Learn more about the project here.",
                          "languageCode": "en"
                        }
                      }
                    ],
                    "detailsUrls": [
                      {
                        "url": "https://new.mta.info/"
                      }
                    ],
                    "cause": "OTHER_CAUSE",
                    "startTime": "2026-04-16T04:00:00Z",
                    "endTime": "2026-12-01T04:45:00Z",
                    "attribution": {
                      "link": {
                        "text": "new.mta.info",
                        "url": "https://new.mta.info/"
                      }
                    },
                    "createTime": "2026-05-15T22:39:30Z",
                    "severityLevel": "INFO"
                  }
                ]
              },
              ...
            ]
          },
          ...
        ]
        "stops": [
          {
            "id": "ChIJOfdrigFZwokRJPllLwfPrJY",
            "location": {
              "latitude": 40.752823,
              "longitude": -73.977195999999992
            },
            "wheelchairAccessibleEntrance": true
          }
        ],
        "departureBoards": [
          {
            "displayType": "TIME_CENTRIC",
            "rows": [
              {
                "departures": [
                  {
                    "timedDeparture": {
                      "scheduledTime": "2026-05-15T22:42:00Z",
                      "timingType": "SCHEDULED",
                      "predictedTime": "2026-05-15T22:42:00Z",
                      "updateTime": "2026-05-15T22:38:50Z"
                    },
                    "originallyScheduledStopId": "ChIJOfdrigFZwokRJPllLwfPrJY",
                    "lineId": "ChIJAfBuQhwg6IkRYnFpClHxFrM"
                  }
                ]
              },
              ...
            ]
          }
        ]
      }
    },
    {
      "id": "ChIJ_4EAi-pZwokRWe5T1JmmWmc",
      "displayName": {
        "text": "Grand Central Station",
        "languageCode": "en"
      }
    }
  ]
}

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

נקודות הניווט מחזירות navigationPointToken. אפשר להעביר את האסימון הזה אל Navigation SDK (זמין ל-Android או ל-iOS) או אל Routes API כדי להנחות את הנהגים אל המיקום הספציפי הזה. מידע נוסף זמין במאמר אסימונים של נקודות ניווט.

בדוגמה הבאה מוצגת בקשה לחיפוש טקסט (חדש) של 'נמל התעופה הבינלאומי של סן פרנסיסקו' שכוללת את entrances ואת navigationPoints במסכת השדות:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.entrances,places.navigationPoints" \
-d '{
  "textQuery": "San Francisco International Airport",
  "pageSize": 1
}' \
"https://places.googleapis.com/v1/places:searchText"

התשובה כוללת את הכניסות ואת נקודות הניווט למקום:

{
  "places": [
    {
      "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ",
      "displayName": {
        "text": "San Francisco International Airport",
        "languageCode": "en"
      },
      "entrances": [
        {
          "location": {
            "latitude": 37.6172154,
            "longitude": -122.3839724
          }
        },
        {
          "location": {
            "latitude": 37.6174073,
            "longitude": -122.384196
          }
        },
        ...
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...",
          "displayName": {
            "text": "International Terminal Departures Level",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6153121,
            "longitude": -122.3900833
          },
          "travelModes": ["WALK"]
        },
        {
          "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...",
          "displayName": {
            "text": "Domestic Garage - SFO Short Term Parking",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6157153,
            "longitude": -122.3885012
          },
          "travelModes": ["DRIVE", "WALK"],
          "usages": ["PARKING"]
        },
        ...
      ]
    }
  ]
}

רוצה לנסות?

‫APIs Explorer מאפשר לכם לשלוח בקשות לדוגמה כדי להכיר את ה-API ואת האפשרויות שלו.

בצד שמאל של הדף, לוחצים על סמל ה-API‏ api.
אפשר לערוך את הפרמטרים של הבקשה.
לוחצים על הכפתור Execute (הפעלה). בתיבת הדו-שיח, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.
בחלונית APIs Explorer, לוחצים על סמל המסך המלא fullscreen כדי להרחיב את החלון של APIs Explorer.

חיפוש טקסט (חדש) קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מבוא

בקשות לחיפוש טקסט (חדש)

תשובות של חיפוש טקסט (חדש)

פרמטרים נדרשים

FieldMask

textQuery

פרמטרים אופציונליים

includeFutureOpeningBusinesses

includedType

includePureServiceAreaBusinesses

languageCode

locationBias

locationRestriction

maxResultCount (הוצא משימוש)

evOptions

connectorTypes

minimumChargingRateKw

minRating

openNow

pageSize

pageToken

priceLevels

rankPreference

regionCode

strictTypeFiltering