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

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

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

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

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

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

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

    X-Goog-FieldMask: *

    צריך לציין אחד או יותר מהשדות הבאים:

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

      places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.displayName, places.formattedAddress, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name*, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.shortFormattedAddress, places.subDestinationsplaces.nameplaces.typesplaces.utcOffsetMinutesplaces.viewport

      places/PLACE_ID משתמשים ב-places.displayName כדי לגשת לשם הטקסט של המקום.

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

      places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, 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.liveMusicplaces.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout

  • locationRestriction

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

    לדוגמה:

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

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

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

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

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

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

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

רוצה לנסות?

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

  1. אפשר להרחיב את האפשרות הצג פרמטרים סטנדרטיים ולהגדיר את הפרמטר fields כאנונימיזציה של שדות.
  2. אפשר לערוך את גוף הבקשה.
  3. לוחצים על הלחצן ביצוע. בחלון הקופץ, בוחרים את החשבון שרוצים להשתמש בו כדי לשלוח את הבקשה.