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

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

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

מבוא

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

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

בעזרת 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

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

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

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

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    אפשר להשתמש ב-* כדי לאחזר את כל השדות.

    X-Goog-FieldMask: *

    מציינים אחד או יותר מהשדות הבאים:

    • השדות הבאים מפעילים את המק"ט "חיפוש טקסט בסיסי – מזהה בלבד":

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

  • locationBias

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

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

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

    • מעגל מוגדר לפי נקודת מרכז ורדיוס במטרים. הרדיוס חייב להיות בין 0.0 ל-50,000.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

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

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

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

  • 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). מקומות עם קצב טעינה נמוך מקצב הטעינה המינימלי מסוננים החוצה. לדוגמה, כדי למצוא מטענים לרכב חשמלי עם קצב טעינה של לפחות 10kW, אפשר להגדיר את הפרמטר הזה לערך "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, שיוצגו בכל דף. לדוגמה, אם מגדירים את הערך של pageSize ל-5, יוחזרו עד 5 תוצאות בדף הראשון. אם השאילתה יכולה להחזיר תוצאות נוספות, התגובה כוללת nextPageToken שאפשר להעביר בבקשה הבאה כדי לגשת לדף הבא.

    השדה הזה מחליף את השדה maxResultCount שהוצא משימוש. אם מציינים גם את pageSize וגם את maxResultCount, ה-API משתמש ב-pageSize ומתעלם מ-maxResultCount.

  • pageToken

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

  • priceLevels

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

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

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

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

    לדוגמה:

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]

  • 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 (ברירת המחדל), התגובה יכולה להכיל מקומות שלא תואמים לסוגים שצוינו.

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

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

בדוגמה הבאה מוצגת בקשה לחיפוש טקסט (חדש) של "Spicy Vegetarian Food in Sydney, Australia":

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"
      }
    },
    ...
  ]
}

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

כדי להגביל את תוצאות השאילתה לאזור מסוים, משתמשים בפרמטר 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, עם קצב טעינה מינימלי של 10kW, ב-Mountain View, קליפורניה. מוחזרות רק ארבע תוצאות.

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"
          },
          ...
        ]
      }
    },
    {
      "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"
          }
        ]
      }
    },
    ...
  ]
}

חיפוש נותני שירות באזור מוגדר (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"
      }
    },
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "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"
    },
    ...
  ],
  "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"
    },
    ...
  ],
  "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
          },
          ...
        ],
        "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"
          },
          ...
        ]
      }
    },
    ...
  ]
}

איך למצוא עסקים שייפתחו בעתיד

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

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 Station":

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

בדוגמה הבאה מוצגת בקשה לחיפוש טקסט (חדש) של "San Francisco International Airport" שכוללת את 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 ואת האפשרויות שהוא מציע.

  1. לוחצים על סמל ה-API‏ api בצד שמאל של הדף.

  2. אפשר לערוך את הפרמטרים של הבקשה.

  3. לוחצים על הכפתור Execute. בתיבת הדו-שיח, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.

  4. בחלונית APIs Explorer, לוחצים על סמל המסך המלא fullscreen כדי להרחיב את החלון של APIs Explorer.