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

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

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

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

https://maps.googleapis.com/maps/api/place/nearbysearch/output?parameters

כאשר output יכול להיות אחד מהערכים הבאים:

• ‫json (מומלץ) מציין פלט ב-JavaScript Object Notation ‏ (JSON)
• ‫xml מציין פלט בפורמט XML

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

פרמטרים נדרשים

• location

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

• רדיוס

  מגדיר את המרחק (במטרים) שבו יוחזרו תוצאות של מקומות. כדי להטות את התוצאות למעגל מסוים, אפשר להעביר את הפרמטרים location ו-radius. כך שירות Places מקבל הוראה להעדיף להציג תוצאות בתוך המעגל הזה, אבל עדיין יכול להיות שיוצגו תוצאות מחוץ לאזור שהוגדר.

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

  • השלמה אוטומטית: 50,000 מטרים
  • חיפוש בסביבה:
    • עם keyword או name: ‏50,000 מטרים
    • בלי keyword או name
      • עד 50,000 מטרים, מותאם באופן דינמי על סמך צפיפות האזור, ללא תלות בפרמטר rankby.
      • כשמשתמשים ב-rankby=distance, הפרמטר radius לא יתקבל ותתקבל השגיאה INVALID_REQUEST.
  • השלמה אוטומטית של שאילתות: 50,000 מטרים
  • חיפוש טקסט: 50,000 מטרים

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

• מילת מפתח

  מחרוזת הטקסט שרוצים לחפש, לדוגמה: "מסעדה" או "רחוב הרצל 123". הערך צריך להיות שם של מקום, כתובת או קטגוריה של עסקים. כל סוג אחר של קלט עלול לגרום לשגיאות, ואין ערובה לכך שיתקבלו תוצאות תקינות. שירות Google Places יחזיר התאמות אפשריות על סמך המחרוזת הזו ויסדר את התוצאות לפי הרלוונטיות המשוערת שלהן.

  הכללה מפורשת של נתוני מיקום באמצעות הפרמטר הזה עלולה להתנגש עם הפרמטרים location,‏ radius ו-rankby, ולגרום לתוצאות לא צפויות.

  אם הפרמטר הזה לא נכלל, מקומות עם הערך CLOSED_TEMPORARILY או CLOSED_PERMANENTLY ב-business_status לא יוחזרו.

• language

  השפה שבה התוצאות יוחזרו.

  • כאן אפשר לעיין ברשימת השפות הנתמכות. ‫Google מעדכנת את השפות הנתמכות לעיתים קרובות, לכן יכול להיות שהרשימה הזו לא מלאה.
  • אם לא מציינים את הפרמטר language, ה-API מנסה להשתמש בשפה המועדפת שצוינה בכותרת Accept-Language.
  • ה-API מנסה לספק כתובת רחוב שקריאה גם למשתמש וגם למקומיים. כדי להשיג את המטרה הזו, הוא מחזיר כתובות רחוב בשפה המקומית, עם תעתיק לכתב שהמשתמש יכול לקרוא במידת הצורך, תוך התחשבות בשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מהרכיב הראשון.
  • אם השם לא זמין בשפה המועדפת, ה-API משתמש בהתאמה הקרובה ביותר.
  • השפה המועדפת משפיעה קצת על קבוצת התוצאות שה-API בוחר להחזיר ועל הסדר שבו הן מוחזרות. הכלי להמרת כתובות לקואורדינטות מפרש קיצורים באופן שונה בהתאם לשפה, כמו קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת. לדוגמה, utca ו-tér הן מילים נרדפות ל"רחוב" בהונגרית.

• maxprice

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

• minprice

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

• שם

  שווה ערך ל-keyword. הערכים בשדה הזה משולבים עם הערכים בשדה keyword ומועברים כחלק מאותה מחרוזת חיפוש.

• opennow

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

• pagetoken

  הפונקציה מחזירה עד 20 תוצאות מחיפוש שהופעל בעבר. הגדרת הפרמטר pagetoken מפעילה חיפוש עם אותם פרמטרים שבהם השתמשתם קודם – המערכת מתעלמת מכל הפרמטרים חוץ מ-pagetoken.

• rankby

  מציין את הסדר שבו התוצאות מופיעות. הערכים שאפשר לבחור הם:

  • ‫prominence (ברירת המחדל). האפשרות הזו ממיינת את התוצאות לפי החשיבות שלהן. הדירוג יתעדף מקומות בולטים בתוך הרדיוס שהוגדר על פני מקומות בסביבה שתואמים אבל פחות בולטים. הבולטוּת יכולה להיות מושפעת מהדירוג של המקום באינדקס של Google, מהפופולריות שלו בעולם ומגורמים אחרים. כשמציינים את מידת הבולטוּת, צריך לציין גם את הפרמטר radius.
  • distance. האפשרות הזו משפיעה על תוצאות החיפוש בסדר עולה לפי המרחק שלהן מהמיקום שצוין. כשמציינים את distance, צריך לציין גם אחד או יותר מהמאפיינים keyword,‏ name או type, ואסור לציין את radius.

• סוג

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

  • ‫type=hospital|pharmacy|doctor הופך ל-type=hospital
  • המערכת מתעלמת לחלוטין מהמדיניות type=hospital,pharmacy,doctor

  לרשימת הסוגים הנתמכים

  הערה: הוספה של keyword וגם type עם אותו ערך (keyword=cafe&type=cafe או keyword=parking&type=parking) יכולה להניב ZERO_RESULTS.

דוגמה לחיפוש בסביבה (דור קודם)

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522%2C151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/nearbysearch/json
  ?keyword=cruise
  &location=-33.8670522%2C151.1957362
  &radius=1500
  &type=restaurant
  &key=YOUR_API_KEY

הערה: בדוגמה הזו, צריך להחליף את הערך key במפתח ה-API שלכם כדי שהבקשה תפעל באפליקציה.

תגובות של חיפוש בסביבה (דור קודם)

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

{
  "html_attributions": [],
  "results":
    [
      {
        "business_status": "OPERATIONAL",
        "geometry":
          {
            "location": { "lat": -33.8587323, "lng": 151.2100055 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85739847010727, "lng": 151.2112436298927 },
                "southwest":
                  { "lat": -33.86009812989271, "lng": 151.2085439701072 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/bar-71.png",
        "icon_background_color": "#FF9E67",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/bar_pinlet",
        "name": "Cruise Bar",
        "opening_hours": { "open_now": false },
        "photos":
          [
            {
              "height": 608,
              "html_attributions":
                [
                  'A Google User',
                ],
              "photo_reference": "Aap_uECvJIZuXT-uLDYm4DPbrV7gXVPeplbTWUgcOJ6rnfc4bUYCEAwPU_AmXGIaj0PDhWPbmrjQC8hhuXRJQjnA1-iREGEn7I0ZneHg5OP1mDT7lYVpa1hUPoz7cn8iCGBN9MynjOPSUe-UooRrFw2XEXOLgRJ-uKr6tGQUp77CWVocpcoG",
              "width": 1080,
            },
          ],
        "place_id": "ChIJi6C1MxquEmsR9-c-3O48ykI",
        "plus_code":
          {
            "compound_code": "46R6+G2 The Rocks, New South Wales",
            "global_code": "4RRH46R6+G2",
          },
        "price_level": 2,
        "rating": 4,
        "reference": "ChIJi6C1MxquEmsR9-c-3O48ykI",
        "scope": "GOOGLE",
        "types":
          ["bar", "restaurant", "food", "point_of_interest", "establishment"],
        "user_ratings_total": 1269,
        "vicinity": "Level 1, 2 and 3, Overseas Passenger Terminal, Circular Quay W, The Rocks",
      },
      {
        "business_status": "OPERATIONAL",
        "geometry":
          {
            "location": { "lat": -33.8675219, "lng": 151.2016502 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.86614532010728, "lng": 151.2031259298927 },
                "southwest":
                  { "lat": -33.86884497989272, "lng": 151.2004262701072 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/generic_business-71.png",
        "icon_background_color": "#7B9EB0",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet",
        "name": "Sydney Harbour Dinner Cruises",
        "opening_hours": { "open_now": true },
        "photos":
          [
            {
              "height": 835,
              "html_attributions":
                [
                  'A Google User',
                ],
              "photo_reference": "Aap_uEBVsYnNcrpRixtrlHBztigZh70CwYkNWZzQnqJ39SjeBo_wvgKf-kXc6tgaMLBdQrRKmxmSKjOezoZrv-sHKVbTX0OI48HBqYYVnQiZQ-WGeuQDsLEPwX7LaVPa68nUAxX114Zpqt7bryoO9wL4qXdgEnopbOp5WWLALhKEHoIEH7f7",
              "width": 1200,
            },
          ],
        "place_id": "ChIJM1mOVTS6EmsRKaDzrTsgids",
        "plus_code":
          {
            "compound_code": "46J2+XM Sydney, New South Wales",
            "global_code": "4RRH46J2+XM",
          },
        "rating": 4.8,
        "reference": "ChIJM1mOVTS6EmsRKaDzrTsgids",
        "scope": "GOOGLE",
        "types":
          [
            "tourist_attraction",
            "travel_agency",
            "restaurant",
            "food",
            "point_of_interest",
            "establishment",
          ],
        "user_ratings_total": 9,
        "vicinity": "32 The Promenade, Sydney",
      },
      // ...
    ],
  "status": "OK",
}
    

<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>Cruise Bar</name>
  <vicinity>Level 1, 2 and 3, Overseas Passenger Terminal, Circular Quay W, The Rocks</vicinity>
  <type>bar</type>
  <type>restaurant</type>
  <type>food</type>
  <type>point_of_interest</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8587323</lat>
    <lng>151.2100055</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8600981</lat>
     <lng>151.2085440</lng>
    </southwest>
    <northeast>
     <lat>-33.8573985</lat>
     <lng>151.2112436</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.0</rating>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/bar-71.png</icon>
  <reference>ChIJi6C1MxquEmsR9-c-3O48ykI</reference>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
  <photo>
   <photo_reference>Aap_uEALIq4sgBHhIYWWapOH2NV1T2I7YdOiLzEH7z-483I764cId1sZkbzSq-hVYTk1PQeaHuZzlRfA7-ilwJ3QWon4b37ePd-PBwZbOwFZHxhYs0Cs7jRSgMHWfOzGivp6ZFG4iupyz50qS5pBZT1WbA2ufacTq_U21TtgffQD31wKRPQk</photo_reference>
   <width>1080</width>
   <height>608</height>
   <html_attribution>&lt;a href=&quot;https://maps.google.com/maps/contrib/112582655193348962755&quot;&gt;A Google User&lt;/a&gt;</html_attribution>
  </photo>
  <price_level>2</price_level>
  <user_ratings_total>1269</user_ratings_total>
  <place_id>ChIJi6C1MxquEmsR9-c-3O48ykI</place_id>
  <scope>GOOGLE</scope>
  <plus_code>
   <global_code>4RRH46R6+G2</global_code>
   <compound_code>46R6+G2 The Rocks, New South Wales</compound_code>
  </plus_code>
  <icon_background_color>#FF9E67</icon_background_color>
  <business_status>OPERATIONAL</business_status>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/bar_pinlet</icon_mask_base_uri>
 </result>
 <result>
  <name>Sydney Harbour Dinner Cruises</name>
  <vicinity>32 The Promenade, Sydney</vicinity>
  <type>tourist_attraction</type>
  <type>restaurant</type>
  <type>food</type>
  <type>travel_agency</type>
  <type>point_of_interest</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8675219</lat>
    <lng>151.2016502</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8688450</lat>
     <lng>151.2004263</lng>
    </southwest>
    <northeast>
     <lat>-33.8661453</lat>
     <lng>151.2031259</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.8</rating>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/generic_business-71.png</icon>
  <reference>ChIJM1mOVTS6EmsRKaDzrTsgids</reference>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>Aap_uEB5jH7GXdcozv1Y5HX18syo4f128S58NVUnqBbLJMpWbC39K49wp-wzsLOsUT8QKDaag6ISFL8hl1vVuig4jkc5fMMkWKiqw5PY-ebcWZ5tI3gEXEYGGoG_mDAulaMLudUpSwgBx2_RLnA0SSiugqqQUTYlkGyCZSe8HSyngVczy6XN</photo_reference>
   <width>1200</width>
   <height>835</height>
   <html_attribution>&lt;a href=&quot;https://maps.google.com/maps/contrib/109764923610545394994&quot;&gt;A Google User&lt;/a&gt;</html_attribution>
  </photo>
  <user_ratings_total>9</user_ratings_total>
  <place_id>ChIJM1mOVTS6EmsRKaDzrTsgids</place_id>
  <scope>GOOGLE</scope>
  <plus_code>
   <global_code>4RRH46J2+XM</global_code>
   <compound_code>46J2+XM Sydney, New South Wales</compound_code>
  </plus_code>
  <icon_background_color>#7B9EB0</icon_background_color>
  <business_status>OPERATIONAL</business_status>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet</icon_mask_base_uri>
 </result>
 <!-- ... -->
</PlaceSearchResponse>

    

PlacesNearbySearchResponse

PlacesSearchStatus

קודי סטטוס שמוחזרים על ידי השירות.

• ‫OK, שמציין שבקשת ה-API בוצעה בהצלחה.
• ‫ZERO_RESULTS, שמציין שהחיפוש הצליח אבל לא הניב תוצאות. זה יכול לקרות אם החיפוש הועבר אל latlng במיקום מרוחק.
• ‫INVALID_REQUEST, שמציין שהפורמט של בקשת ה-API היה שגוי, בדרך כלל בגלל שחסר פרמטר נדרש של שאילתה (location או radius).
• OVER_QUERY_LIMIT שמציינת אחת מהאפשרויות הבאות:
  • חרגתם ממגבלות ה-QPS.
  • החיוב לא הופעל בחשבון שלכם.
  • חרגתם מהקרדיט החודשי בסך 200 $או ממכסת השימוש שהגדרתם בעצמכם.
  • אמצעי התשלום שסופק כבר לא תקף (לדוגמה, פג התוקף של כרטיס האשראי).
  בשאלות הנפוצות בנושא מפות מוסבר איך לפתור את השגיאה הזו.
• REQUEST_DENIED, שמציין שהבקשה נדחתה, בדרך כלל מהסיבות הבאות:
  • בבקשה חסר מפתח API.
  • הפרמטר key לא תקין.
• ‫UNKNOWN_ERROR מציין שגיאה לא ידועה.

מקום

התגובות של חיפוש מקומות מחזירות את קבוצת המשנה הבאה של שדות Place. חלק מהמאפיינים זמינים רק לסוגי מקומות מסוימים. כדי לאחזר שדות שלא מוחזרים על ידי חיפוש מקומות, כמו address_components,‏ formatted_phone_number,‏ reviews או website, צריך להעביר את הערך של place_id שמוחזר בבקשה של Place Details (מדור קודם). כדי לראות את זמינות השדות ורמות התמחור בנקודות הקצה השונות, קראו את המאמר שדות נתונים של מקומות (גרסה קודמת).

גישה לתוצאות נוספות

כברירת מחדל, כל תגובה מחזירה עד 20 תוצאות של establishment לכל שאילתה. עם זאת, כל חיפוש יכול להחזיר עד 60 תוצאות, שמחולקות לשלושה דפים. אם החיפוש יחזיר יותר מ-20 תוצאות, תגובת החיפוש תכלול ערך נוסף – next_page_token. כדי לראות את קבוצת התוצאות הבאה, מעבירים את הערך של next_page_token לפרמטר pagetoken של בקשה חדשה.

• אם הערך של next_page_token הוא null או לא מוחזר, אין תוצאות נוספות.
• אם תנסו שוב לשלוח את הבקשה עם אותו next_page_token, תקבלו את דף התוצאות הבא.
• אם מגדירים את pagetoken, המערכת תתעלם מכל הפרמטרים האחרים.
• אפשר לבקש דף חדש עד פעמיים אחרי השאילתה המקורית.
• כל בקשה, כולל בקשה באמצעות next_page_token, נספרת כבקשה אחת במגבלות השימוש ומחויבת בנפרד.
• יש עיכוב של כמה שניות בין המועד שבו מונפקת next_page_token לבין המועד שבו היא נכנסת לתוקף. אם תבקשו את הדף הבא לפני שהוא יהיה זמין, תקבלו תגובה מסוג INVALID_REQUEST. בקשות עם next_page_token תמיד מחויבות.

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

{
   "html_attributions" : [],
   "next_page_token" : "CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q",
   "results" : [...]
   "status" : "OK"
}

כדי לראות את קבוצת התוצאות הבאה, אפשר לשלוח שאילתה חדשה ולהעביר את התוצאה של next_page_token לפרמטר pagetoken. לדוגמה:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?pagetoken=CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q&key=YOUR_API_KEY