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

הפלטפורמה: Android iOS JavaScript Web Service
מפתחים באזור הכלכלי האירופי (EEA)

מבוא

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

‫APIs Explorer מאפשר לכם לשלוח בקשות בזמן אמת כדי להכיר את ה-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

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

התגובה של Nearby Search (חדש) היא אובייקט 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: *

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

    • השדות הבאים מפעילים את מק"ט Nearby Search Pro:

      places.accessibilityOptions
      places.addressComponents
      places.addressDescriptor*
      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.movedPlace
      places.movedPlaceId
      places.photos
      places.plusCode
      places.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.subDestinations
      places.types
      places.utcOffsetMinutes
      places.viewport

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

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

    • השדות הבאים מפעילים את מק"ט Nearby Search Enterprise:

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

    • השדות הבאים מפעילים את מק"ט Nearby Search 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

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

  • locationRestriction

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

    לדוגמה: 

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

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

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

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

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

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

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

curl -X POST -d '{
  "maxResultCount": 5,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      },"radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"],
  "excludedTypes": [],
  "rankPreference":"POPULARITY"
}' \
-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:searchNearby

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

  {
    "places": [
      {
        "displayName": {
          "text": "Westfield Valley Fair",
          "languageCode": "en"
        },
        "addressDescriptor": {
          "landmarks": [
            {
              "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": 114.76984,
              "travelDistanceMeters": 114.261856
            },
            {
              "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "displayName": {
                "text": "Valley Fair Mall Eyexam of CA",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "health",
                "point_of_interest"
              ],
              "straightLineDistanceMeters": 131.62566,
              "travelDistanceMeters": 237.33253
            },
            {
              "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "displayName": {
                "text": "Din Tai Fung",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "food",
                "point_of_interest",
                "restaurant"
              ],
              "straightLineDistanceMeters": 110.0775,
              "travelDistanceMeters": 171.41951
            },
            {
              "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "displayName": {
                "text": "Abercrombie & Fitch",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 53.620117,
              "travelDistanceMeters": 2.4578214
            },
            {
              "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "displayName": {
                "text": "Hollister Co.",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 56.53726,
              "travelDistanceMeters": 15.418246
            }
          ],
          "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": "OUTSKIRTS"
            }
          ]
        }
      },
  /.../
  }

רוצה לנסות?

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

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

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

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

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