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

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

  התו הכללי לחיפוש '*' בוחר את כל השדות. עם זאת, למרות שמותר להשתמש בתו הכללי הזה בפיתוח, Google לא ממליצה להשתמש במסכה של שדה התגובה עם התו הכללי לחיפוש (*) בסביבת הייצור, בגלל הכמות הגדולה של הנתונים שאפשר להחזיר.
  הנחיות נוספות לשימוש ב-places.iconMaskBaseUri וב-places.iconBackgroundColor זמינות בקטע סמלי מקומות.

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

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

    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.nameplaces.subDestinationsplaces.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 סוגים בכל קטגוריית הגבלת סוגים.

  הערה: הערכים בטבלה ב' מוחזרים רק בתגובה. לא ניתן להשתמש בערכים בטבלה B כמסנן.

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

  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. לוחצים על סמל ה-API בצד שמאל של הדף.
2. אפשר להרחיב את האפשרות הצג פרמטרים סטנדרטיים ולהגדיר את הפרמטר fields כאנונימיזציה של שדות.
3. אפשר לערוך את גוף הבקשה.
4. לוחצים על הלחצן ביצוע. בחלון הקופץ, בוחרים את החשבון שבאמצעותו רוצים לשלוח את הבקשה.

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