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

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

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

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

"10 High Street, UK" או "123 Main Street, US" רחובות רבים שנקראים 'High Street' בבריטניה, רחובות רבים שנקראים 'Main Street' בארצות הברית. השאילתה לא מחזירה תוצאות רצויות, אלא אם מגדירים הגבלת מיקום.
'ChainRestaurant New York' כמה מיקומים של 'ChainRestaurant' בניו יורק, ללא רחוב או שם רחוב.
"10 High Street, Escher UK" או "123 Main Street, Pleasanton US" יש רק רחוב אחד בשם 'High Street' בעיר Escher בבריטניה, ורק רחוב אחד בשם 'Main Street' בעיר Pleasanton בקליפורניה, ארה"ב.
"UniqueRestaurantName New York" יש רק מוסד אחד בשם הזה בניו יורק, ולכן אין צורך בכתובת רחוב כדי להבדיל בינו לבין מוסדות אחרים.
"pizza restaurants in New York" השאילתה הזו מכילה את הגבלת המיקום שלה, ו'פיצריות' הוא סוג מקום מוגדר היטב. הפונקציה מחזירה כמה תוצאות.
‎+1 514-670-8700‎

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

ב-API 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: *

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

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

      places.attributions, places.id, places.name*, nextPageToken

      * השדה places.name מכיל את שם המשאב של המקום בפורמט: places/PLACE_ID. משתמשים ב-places.displayName כדי לגשת לשם הטקסט של המקום.

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

      places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.containingPlaces, places.displayName, places.formattedAddress, places.googleMapsLinks*, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.location, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.pureServiceAreaBusiness, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport

      * השדה places.googleMapsLinks נמצא בשלב התצוגה המקדימה לפני GA, והוא לא כרוך בתשלום, כלומר החיוב הוא 0 $על השימוש במהלך התצוגה המקדימה.

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

      places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.priceRange, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri

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

      places.allowsDogs, places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom, places.reviews, places.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 מחזיר התאמות של מועמדים על סמך המחרוזת הזו ומסדר את התוצאות לפי מידת הרלוונטיות המשוערת שלהן.

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

  • includedType

    הגבלת התוצאות למקומות שתואמים לסוג שצוין בטבלה א'. אפשר לציין רק סוג אחד. לדוגמה:

    • "includedType":"bar"
    • "includedType":"pharmacy"

  • includePureServiceAreaBusinesses

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

  • languageCode

    השפה שבה יוצגו התוצאות.

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

  • locationBias

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

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

      צריך לאכלס את הערכים של low ו-high, והתיבה המיוצגת לא יכולה להיות ריקה. תצוגת חלון ריקה גורמת לשגיאה.

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

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • locationRestriction

    מציין אזור לחיפוש. לא יוצגו תוצאות מחוץ לאזור שצוין.

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

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

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

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

  • evOptions

    פרמטרים לזיהוי מחברי הטעינה לרכב חשמלי (EV) ושיעורי הטעינה הזמינים.

    • connectorTypes

      סינון לפי סוג מחבר הטעינה לרכב חשמלי שזמין במקום. מקומות שלא תומכים באף אחד מסוגי המחברים יימחקו מהמסנן. סוגי המחברים הנתמכים לטעינה של רכב חשמלי כוללים מטענים משולבים (AC ו-DC), מטענים של Tesla, מטענים שתואמים ל-GB/T (לטעינה מהירה של רכב חשמלי בסין) ומטענים לשקע חשמל. מידע נוסף זמין במאמרי העזרה.

    • minimumChargingRateKw

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

  • pageSize

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

  • pageToken

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

  • priceLevels

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

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

    לדוגמה:

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

  • rankPreference

    קובע איך התוצאות מדורגות בתגובה על סמך סוג השאילתה:

    • בשאילתה קטגורית כמו 'מסעדות בניו יורק', הערך שמוגדר כברירת מחדל הוא RELEVANCE (דירוג התוצאות לפי רלוונטיות לחיפוש). אפשר להגדיר את rankPreference לערך RELEVANCE או DISTANCE (מיון התוצאות לפי מרחק).
    • בשאילתה לא קטגוריאלית, כמו 'רמת גן, תל אביב', מומלץ להשאיר את rankPreference ללא הגדרה.

  • regionCode

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

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

    רוב קודי CLDR זהים לקודי ISO 3166-1, מלבד כמה חריגים בולטים. לדוגמה, הדומיין ברמה העליונה של בריטניה הוא ‎"uk" (‎.co.uk), והקוד שלו לפי תקן ISO 3166-1 הוא ‎"gb" (טכנית, הישות היא ‎"The United Kingdom of Great Britain and Northern Ireland"). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

  • strictTypeFiltering

    משמש עם הפרמטר includedType. כשהערך מוגדר ל-true, מוצגים רק מקומות שתואמים לסוגים שצוינו ב-includeType. כשהערך הוא 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

אפשר להשתמש בפרמטר 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'

חיפוש עמדות טעינה לרכב חשמלי (EV) עם קצב טעינה מינימלי

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

בדוגמה הבאה מוצגת בקשה למחברים לטעינה של רכבים חשמליים מסוג Tesla ו-J1772 מסוג 1, עם קצב טעינה מינימלי של 10kW ב-Mountain View,‏ CA. רק ארבע תוצאות יחזרו.

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
          }
        ]
      }
    }
  ]
}

חיפוש עסקים שנותנים שירות באזור מוגדר

משתמשים בפרמטר 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"
}

נסה בעצמך!

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

  1. בוחרים בסמל ה-API, מרחיבים את API Explorer., בצד שמאל של הדף.

  2. אפשר גם להרחיב את האפשרות Show standard parameters ולהגדיר את הפרמטר fields למסכת השדה.

  3. אם רוצים, עורכים את גוף הבקשה.

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

  5. בחלונית של API Explorer, בוחרים בסמל ההרחבה מרחיבים את API Explorer. כדי להרחיב את החלון של API Explorer.