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

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

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

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

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

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

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

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

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

• קלט

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

• inputtype

  סוג הקלט. הערך יכול להיות textquery או phonenumber. מספרי הטלפון צריכים להיות בפורמט לחיוג בינלאומי (מתחילים בסימן פלוס ("+"), ואחריו קידומת המדינה ומספר הטלפון עצמו). למידע נוסף, ראו המלצת ITU‏ E.164.

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

• Fields

  זהירות: בקשות של חיפוש מקומות (דור קודם) ובקשות של פרטי מקומות (דור קודם) לא מחזירות את אותם שדות. בקשות של חיפוש מקומות (דור קודם) מחזירות קבוצת משנה של השדות שמוחזרים על ידי בקשות של Place Details (דור קודם). אם השדה הרצוי לא מוחזר על ידי חיפוש מקומות (הגרסה הקודמת), אפשר להשתמש בחיפוש מקומות (הגרסה הקודמת) כדי לקבל place_id, ואז להשתמש במזהה המקום הזה כדי לשלוח בקשה לפרטי מקום (הגרסה הקודמת). מידע נוסף על השדות שלא זמינים בבקשה של חיפוש מקומות (הגרסה הקודמת) מופיע במאמר תמיכה בשדות של Places API.

  משתמשים בפרמטר fields כדי לציין רשימה מופרדת בפסיקים של סוגי נתוני המקומות שרוצים להחזיר. לדוגמה: fields=formatted_address,name,geometry. צריך להשתמש בלוכסן כשמציינים ערכים מורכבים. לדוגמה: opening_hours/open_now.

  השדות מחולקים לשלוש קטגוריות חיוב: בסיסי, יצירת קשר ואווירה. שדות בסיסיים מחויבים בתעריף הבסיס, ושדות של פרטי קשר ואווירה מחויבים בתעריף גבוה יותר. מק"טים של Basic,‏ Contact ו-Atmosphere מחויבים בנוסף למק"ט הבסיסי (Place Details,‏ חיפוש מקום,‏ חיפוש בסביבה או חיפוש טקסט) של הבקשה שהפעילה אותם. למידע נוסף, תוכלו לעיין במחירון.

  Basic

  הקטגוריה "בסיסי" כוללת את השדות הבאים: address_components, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color, name, permanently_closed (הוצא משימוש), photo, place_id, plus_code, type, url, utc_offset, vicinity, wheelchair_accessible_entrance.

  יצירת קשר

  הקטגוריה "איש קשר" כוללת את השדות הבאים: current_opening_hours, formatted_phone_number, international_phone_number, opening_hours, secondary_opening_hours, website

  אווירה

  הקטגוריה "אווירה" כוללת את השדות הבאים: curbside_pickup, delivery, dine_in, editorial_summary, price_level, rating, reservable, reviews, serves_beer, serves_breakfast, serves_brunch, serves_dinner, serves_lunch, serves_vegetarian_food, serves_wine, takeout, user_ratings_total.

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

• language

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

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

• locationbias

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

  • הטיית IP: הנחיה ל-API להשתמש בהטיית כתובת IP. מעבירים את המחרוזת ipbias (לאפשרות הזו אין פרמטרים נוספים).
  • מעגלי: מחרוזת שמציינת את הרדיוס במטרים, וגם קו רוחב/קו אורך במעלות עשרוניות. צריך להשתמש בפורמט הבא: circle:radius@lat,lng.
  • מלבני: מחרוזת שמציינת שני זוגות של קווי רוחב/אורך במעלות עשרוניות, שמייצגים את הנקודות הדרומית/מערבית והצפונית/מזרחית של מלבן. צריך להשתמש בפורמט הבא:rectangle:south,west|north,east. שימו לב שהערכים של מזרח/מערב מוגבלים לטווח של ‎-180, 180, והערכים של צפון/דרום מוגבלים לטווח של ‎-90, 90.

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

בדוגמה הבאה מוצגת בקשה לחיפוש מקום (ממשק קודם) עבור "Museum of Contemporary Art Australia", כולל השדות photos,‏ formatted_address,‏ name,‏ rating,‏ opening_hours ו-geometry:

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Museum%20of%20Contemporary%20Art%20Australia&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Museum%20of%20Contemporary%20Art%20Australia
    &inputtype=textquery
    &key=YOUR_API_KEY

בדוגמה הבאה מוצגת בקשה של חיפוש מקום (מדור קודם) ל-"Mongolian Grill", באמצעות הפרמטר locationbias כדי להעדיף תוצאות בטווח של 2,000 מטרים מהקואורדינטות שצוינו:

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Mongolian%20Grill&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&locationbias=circle:2000@−33.866,151.216&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Mongolian%20Grill
    &inputtype=textquery
    &locationbias=circle:2000@−33.866,151.216
    &key=YOUR_API_KEY

בדוגמה הבאה מוצגת בקשה לחיפוש מקום (ממשק קודם) לפי מספר טלפון. שימו לב שהקידומת "+" של השיחה הבינלאומית קודדה ל-%2B כדי שהבקשה תהיה כתובת URL תקינה. אם לא מקודדים את הקידומת +, היא תפוענח כרווח בשרת, וכתוצאה מכך החיפוש של מספר הטלפון לא יהיה תקין.

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=%2B16502530000&inputtype=phonenumber&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=%2B16502530000
    &inputtype=phonenumber
    &key=YOUR_API_KEY

תגובות של Find Place (Legacy)‎

תגובה של Find Place (דור קודם) מכילה רק את סוגי הנתונים שצוינו באמצעות הפרמטר fields, וגם את html_attributions. בדוגמה הבאה מוצגת התגובה לבקשה מסוג "חיפוש מקום (גרסה קודמת)" עבור "Museum of Contemporary Art Australia", כולל השדות formatted_address, ‏ geometry, ‏ name,‏ opening_hours, ‏ photos, ‏ rating.

{
  "candidates":
    [
      {
        "formatted_address": "140 George St, The Rocks NSW 2000, Australia",
        "geometry":
          {
            "location": { "lat": -33.8599358, "lng": 151.2090295 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85824377010728, "lng": 151.2104386798927 },
                "southwest":
                  { "lat": -33.86094342989272, "lng": 151.2077390201073 },
              },
          },
        "name": "Museum of Contemporary Art Australia",
        "opening_hours": { "open_now": false },
        "rating": 4.4,
      },
    ],
  "status": "OK",
}    

<?xml version="1.0" encoding="UTF-8"?>
<FindPlaceFromTextResponse>
 <candidates>
  <name>Museum of Contemporary Art Australia</name>
  <formatted_address>140 George St, The Rocks NSW 2000, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8599358</lat>
    <lng>151.2090295</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8609434</lat>
     <lng>151.2077390</lng>
    </southwest>
    <northeast>
     <lat>-33.8582438</lat>
     <lng>151.2104387</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.4</rating>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
 </candidates>
 <status>OK</status>
</FindPlaceFromTextResponse>

    

PlacesFindPlaceFromTextResponse

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