חיפוש בקרבת מקום (חדש)

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

בקשת Nearby Search (New) מקבלת סוג אחד או יותר של מקום, ומחזירה רשימה של מקומות תואמים באזור שצוין. חובה להשתמש במסכת שדה שמציינת סוג נתונים אחד או יותר. בתכונה 'חיפוש בקרבת מקום' (חדשה) יש תמיכה רק בבקשות POST.

באמצעות API Explorer תוכלו ליצור בקשות בזמן אמת כדי להכיר את ה-API ואת אפשרויות ה-API:

רוצים לנסות?

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

בקשות של חיפוש בקרבת מקום (חדש)

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

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

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

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "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" \
https://places.googleapis.com/v1/places:searchNearby

תשובות לחיפוש בקרבת מקום (חדש)

חיפוש בקרבת מקום (חדש) מחזיר אובייקט 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.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.attributions, places.businessStatus, places.containingPlaces, places.displayName, places.formattedAddress, places.googleMapsLinks*, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name**, 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.name מכיל את שם המשאב של המקום בפורמט: places/PLACE_ID. משתמשים ב-places.displayName כדי לגשת לשם הטקסט של המקום.

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

      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

      * חיפוש טקסט וחיפוש בקרבת מקום בלבד

  • locationRestriction

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

    לדוגמה: 

    "locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

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

  • IncludeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

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

    לכל מקום יכול להיות רק סוג ראשי אחד מהסוגים שמפורטים בטבלה א' שמשויכים אליו. לדוגמה, הסוג הראשי יכול להיות "mexican_restaurant" או "steak_house". אפשר להשתמש ב-includedPrimaryTypes וב-excludedPrimaryTypes כדי לסנן את התוצאות לפי הסוג הראשי של המקום.

    למקום יכולים להיות גם מספר ערכים של סוגים מהסוגים שמפורטים בטבלה א' שמשויכים אליו. לדוגמה, מסעדות יכולות להיות מהסוגים הבאים: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". אפשר להשתמש ב-includedTypes וב-excludedTypes כדי לסנן את התוצאות ברשימת הסוגים שמשויכים למקום.

    כשמציינים סוג ראשי כללי, כמו "restaurant" או "hotel", התגובה יכולה להכיל מקומות עם סוג ראשי ספציפי יותר מזה שצוין. לדוגמה, מציינים לכלול את הסוג הראשי של "restaurant". לאחר מכן, התשובה יכולה לכלול מקומות עם סוג ראשי של "restaurant", אבל היא יכולה לכלול גם מקומות עם סוג ראשי ספציפי יותר, כמו "chinese_restaurant" או "seafood_restaurant".

    אם מציינים חיפוש עם כמה הגבלות סוג, יוחזרו רק מקומות שעומדים בכל ההגבלות. לדוגמה, אם מציינים את הערך {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, המקומות המוחזרים מספקים שירותים שקשורים ל-"restaurant" אבל לא פועלים בעיקר בתור "steak_house".

    includedTypes

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

    excludedTypes

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

    אם מציינים בבקשה גם את הערך של includedTypes ( למשל "school") וגם את הערך של excludedTypes (למשל "primary_school"), התשובה תכלול מקומות שמסווגים כ-"school" אבל לא כ-"primary_school". התגובה כוללת מקומות שתואמים ללפחות אחד מתוך ה-includedTypes ואף אחד מ-excludedTypes.

    אם יש סוגי נתונים מתנגשים, למשל סוג שמופיע גם ב-includedTypes וגם ב-excludedTypes, תוחזר שגיאת INVALID_REQUEST.

    includedPrimaryTypes

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

    excludedPrimaryTypes

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

    אם יש סוגים ראשיים סותרים, למשל סוג שמופיע גם ב-includedPrimaryTypes וגם ב-excludedPrimaryTypes, תוחזר שגיאה מסוג INVALID_ARGUMENT.

  • languageCode

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

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

  • maxResultCount

    מציין את המספר המקסימלי של תוצאות של מקומות שיוחזרו. חייב להיות בין 1 ל-20 (ברירת מחדל) כולל.

  • rankPreference

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

    • POPULARITY (ברירת מחדל) מיון התוצאות לפי הפופולריות שלהן.
    • DISTANCE מיון התוצאות בסדר עולה לפי המרחק שלהן מהמיקום שצוין.

  • regionCode

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

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

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

דוגמאות לחיפוש בקרבת מקום (חדש)

חיפוש מקומות מסוג מסוים

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

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "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" \
https://places.googleapis.com/v1/places:searchNearby

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

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

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

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "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,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

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

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

חיפוש מקומות מסוגים שונים

בדוגמה הבאה מוצגת בקשה לחיפוש בקרבת מקום (חדש) של שמות התצוגה של כל חנויות הנוחות והחנויות לממכר משקאות ברדיוס של 1,000 מטר מה-circle שצוין:

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby
בדוגמה הזו מוסיפים את השדות places.primaryType ו-places.types למסכת השדה, כדי שהתגובה תכלול את פרטי הסוג של כל מקום. כך קל יותר לבחור את המקום המתאים מהתוצאות.

בדוגמה הבאה מוצגת בקשה לחיפוש בקרבת מקום (חדש) לכל המקומות מסוג "school", לא כולל כל המקומות מסוג "primary_school", והתוצאות מדורגות לפי מרחק:

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

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

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

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

נסה בעצמך!

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

  1. בצד שמאל של הדף, בוחרים בסמל ה-API מרחיבים את API Explorer..
  2. אפשר גם להרחיב את האפשרות Show standard parameters ולהגדיר את הפרמטר fields למסכת השדה.
  3. אם רוצים, עורכים את גוף הבקשה.
  4. לוחצים על הלחצן Execute. בחלון הקופץ, בוחרים את החשבון שבו רוצים להשתמש לצורך שליחת הבקשה.

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