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

לחפש יעדים

מפתחים באזור הכלכלי האירופי (EEA)

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

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

בקשה לחיפוש יעדים

בקשה לחיפוש יעדיםהיא בקשת HTTP POST לכתובת URL בתבנית:

https://geocode.googleapis.com/v4beta/geocode/destinations

מעבירים את כל הפרמטרים בגוף בקשת ה-JSON או בכותרות כחלק מבקשת ה-POST. לדוגמה:

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4beta/geocode/destinations

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

כתובת
מזהה מקום
קואורדינטות של אורך ורוחב

חיפוש יעד לפי כתובת

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

סוג השאילתה	דוגמה
קואורדינטות של קו הרוחב וקו האורך. במקום זאת, צריך להשתמש בשאילתת מיקום.	"37.422131,-122.084801"
יותר מדי מושגים או אילוצים, כמו שמות של כמה מקומות, כבישים או ערים בשאילתה אחת	"Market Street San Francisco San Jose Airport"
רכיבים של כתובת למשלוח דואר שלא מיוצגים במפות Google	"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco"
שמות של עסקים, רשתות או קטגוריות בשילוב עם מיקומים שבהם הישויות האלה לא זמינות	‫"Tesco near Dallas, Texas"
שאילתות דו-משמעיות עם כמה פרשנויות	"Charger drop-off"
שמות היסטוריים שכבר לא נמצאים בשימוש	"Middlesex United Kingdom"
רכיבים או כוונות לא גיאוספציאליים	"כמה סירות יש בנמל ונטורה?"
שמות לא רשמיים או שמות שנועדו להרשים	"The Jenga" "The Helter Skelter"
ישויות פוליטיות גדולות (ערים, מדינות, ארצות)	"New York City" "California" "USA"
מסלולים ללא כתובות ספציפיות	"1st Ave., NYC, NY" "I-95"

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4beta/geocode/destinations

או כpostalAddress:

curl -X POST -d '{
  "addressQuery": {
    "address": {
      "addressLines": ["601 S Bernardo Ave"],
      "locality": "Sunnyvale",
      "postalCode": "94087",
      "administrativeArea": "CA",
      "regionCode": "US"
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4beta/geocode/destinations

בדרך כלל משתמשים בפורמט postalAddress כשמעבדים רכיבי כתובת שמוזנים בטופס HTML.

חיפוש יעד לפי מזהה מקום

אפשר לאחזר יעד באמצעות מזהה מקום:

curl -X POST -d '{
  "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4beta/geocode/destinations

מזהי מקומות נתמכים

נקודת הקצה Search Destinations (יעדי חיפוש) פועלת בצורה הטובה ביותר עם מזהי מקומות שמייצגים יעדים ספציפיים שאפשר להגיע אליהם.

בדרך כלל יש תמיכה במזהי מקומות מסוגים כמו establishment,‏ point_of_interest,‏ premise,‏ street_address ו-subpremise.

אין תמיכה במזהי מקומות שלא מייצגים מיקומים נפרדים, כמו מזהים שנובעים מטווחים של כתובות (לדוגמה, '10-20 Main St'), מקטעים של מסלול ללא מספר ספציפי או קודי פלוס.

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

"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]

כך תוכלו לוודא שמזהי המקומות שמוחזרים על ידי ההשלמה האוטומטית למקומות הם הכי תואמים לשיטה Search Destinations. חשוב לזכור שהסוג establishment הוא רחב. המסנן הזה נחוץ כדי לכלול הרבה מיקומים של עסקים, אבל הוא עשוי לכלול גם תוצאות של השלמה אוטומטית למקומות מסוג natural_feature, שיש להם תמיכה מוגבלת בלבד ב'יעדים לחיפוש'.

חיפוש יעד לפי מיקום

אפשר לחפש יעדים עם קואורדינטות של קו אורך וקו רוחב:

curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4beta/geocode/destinations

שימוש ב-OAuth כדי לשלוח בקשה

‫Geocoding API v4 תומך ב-OAuth 2.0 לאימות. כדי להשתמש ב-OAuth עם Geocoding API, צריך להקצות לטוקן OAuth את ההיקף הנכון. ‫Geocoding API תומך בהיקפים הבאים לשימוש עם נקודת הקצה Destinations:

https://www.googleapis.com/auth/maps-platform.geocode ‫— לשימוש עם כל נקודות הקצה של Geocoding API.

בנוסף, אפשר להשתמש בהיקף הכללי https://www.googleapis.com/auth/cloud-platform לכל נקודות הקצה של Geocoding API. היקף ההרשאות הזה שימושי במהלך הפיתוח, אבל לא בייצור, כי הוא היקף כללי שמאפשר גישה לכל נקודות הקצה.

מידע נוסף ודוגמאות זמינים במאמר בנושא שימוש ב-OAuth.

תגובה של חיפוש יעדים

התשובה של Search Destinations מספקת הקשר עשיר ומקומי מאוד לגבי המיקום.

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

`primary`

המקום העיקרי שזוהה על ידי השאילתה בבקשה.

`containingPlaces`

יחידות גדולות יותר שהיעד הראשי הוא חלק מהן (לדוגמה, קניון שמכיל חנות).

`subDestinations`

מיקומים ספציפיים יותר ביעד הראשי (למשל, דירות בבניין).

`entrances`

האובייקטים במערך entrances[] כוללים את השדות הבאים:

location

זוג קואורדינטות של קו רוחב וקו אורך שמגדיר את המיקום של נקודת הכניסה והיציאה למקום.
entrance_tags[]

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

`structureType`

סוג המבנה שהמקום הזה מייצג.

POINT

מיקום נקודתי.
SECTION

חלק משנה של בניין.
BUILDING

בניין.
GROUNDS

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

`navigationPoints`

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

‫navigationPointToken הוא אסימון שמכיל את המידע ההקשרי בשדה navigationPoints. אפשר לשלוח את הטוקן הזה לממשקי API של ניתוב וניווט כדי לשפר את הניתוב ואת חוויית השימוש באפליקציה. מידע נוסף זמין במאמר ניתוב באמצעות טוקנים של נקודות ניווט.
‫location מכיל את ערכי קו הרוחב וקו האורך של נקודת הניווט. המיקום הזה תמיד יהיה קרוב מאוד לרשת הכבישים, והוא מייצג נקודת עצירה או נקודת התחלה אידיאלית לניווט למקום מסוים וממנו. הנקודה מוסטת בכוונה מעט מקו האמצע של הכביש כדי לסמן בבירור את הצד של הכביש שבו המקום ממוקם.
‫travelModes היא רשימה של אמצעי תחבורה שאפשר להגיע איתם לנקודת הניווט:
- ‫"DRIVE" הוא אמצעי התחבורה שמתאים להוראות נסיעה.
- ‫"WALK" הוא אמצעי התחבורה שמתאים להוראות הגעה בהליכה.
‫usages היא רשימה של שימושים שנתמכים על ידי נקודת הניווט. השימושים יכולים להיות:
- "DROPOFF"
- "PICKUP"
- "PARKING"

`arrivalSummary`

תובנות מבוססות-AI שיעזרו לכם להגיע ליעד. מידע על סיכומים מבוססי-AI

`landmarks`

מקומות בולטים בסביבה כדי לעזור למשתמשים להבין את הסביבה של היעד.

פורמט התשובה

הפונקציה SearchDestinations מחזירה SearchDestinationsResponse בפורמט JSON הבא:

{
  "destinations": [
    {
      "primary": {
        "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w",
        "displayName": {
          "text": "Arby's",
          "languageCode": "en"
        },
        "primaryType": "fast_food_restaurant",
        "types": [
          "fast_food_restaurant",
          "sandwich_shop",
          "deli",
          "meal_takeaway",
          "food_delivery",
          "american_restaurant",
          "restaurant",
          "food_store",
          "store",
          "food",
          "point_of_interest",
          "establishment"
        ],
        "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA",
        "postalAddress": {
          "regionCode": "US",
          "languageCode": "en",
          "postalCode": "94087",
          "administrativeArea": "CA",
          "locality": "Sunnyvale",
          "addressLines": [
            "601 S Bernardo Ave"
          ]
        },
        "structureType": "BUILDING",
        "location": {
          "latitude": 37.3734545,
          "longitude": -122.05693269999998
        },
        "displayPolygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -122.056930138027,
                37.3735253692531
              ],
              [
                -122.056960139391,
                37.3735372663597
              ],
              [
                -122.056994129366,
                37.3734828786847
              ],
              [
                -122.056969677395,
                37.3734731161089
              ],
              [
                -122.057061762447,
                37.3733261309656
              ],
              [
                -122.056979388817,
                37.3732935577128
              ],
              [
                -122.056798860285,
                37.3735818838642
              ],
              [
                -122.056875858081,
                37.3736121235316
              ],
              [
                -122.056930138027,
                37.3735253692531
              ]
            ]
          ]
        }
      },
      "containingPlaces": [
        {
          "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw",
          "displayName": {
            "text": "Cherry Chase Shopping Center",
            "languageCode": "en"
          },
          "primaryType": "shopping_mall",
          "types": [
            "shopping_mall",
            "point_of_interest",
            "establishment"
          ],
          "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA",
          "postalAddress": {
            "regionCode": "US",
            "languageCode": "en",
            "postalCode": "94087-1020",
            "administrativeArea": "CA",
            "locality": "Sunnyvale",
            "addressLines": [
              "663 S Bernardo Ave"
            ]
          },
          "structureType": "GROUNDS",
          "location": {
            "latitude": 37.3731231,
            "longitude": -122.0578211
          },
          "displayPolygon": {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  -122.057112227103,
                  37.3714618008523
                ],
                [
                  -122.057076849821,
                  37.3715743611411
                ],
                [
                  -122.056963607756,
                  37.3719081793948
                ],
                [
                  -122.056865279559,
                  37.3722026053835
                ],
                [
                  -122.056687872374,
                  37.3727258358476
                ],
                [
                  -122.056580005889,
                  37.3730511370747
                ],
                [
                  -122.056498845827,
                  37.3732994782583
                ],
                [
                  -122.056338259713,
                  37.3737878663325
                ],
                [
                  -122.056618678291,
                  37.373887693582
                ],
                [
                  -122.056912102521,
                  37.3740010327191
                ],
                [
                  -122.057532418159,
                  37.3742476426462
                ],
                [
                  -122.057673926626,
                  37.3742441740031
                ],
                [
                  -122.057735663106,
                  37.3742328516943
                ],
                [
                  -122.057766531332,
                  37.3742220604378
                ],
                [
                  -122.057797572967,
                  37.37420520725
                ],
                [
                  -122.057828267759,
                  37.3741852342085
                ],
                [
                  -122.058060299297,
                  37.3740060842535
                ],
                [
                  -122.058199726081,
                  37.3737861673422
                ],
                [
                  -122.05836707267,
                  37.373524542556
                ],
                [
                  -122.058569622393,
                  37.3732018598683
                ],
                [
                  -122.0587638478,
                  37.3728890198039
                ],
                [
                  -122.058934661823,
                  37.3726036257774
                ],
                [
                  -122.059164956851,
                  37.3722498383629
                ],
                [
                  -122.058997784906,
                  37.3721804442035
                ],
                [
                  -122.057936479838,
                  37.3717605636234
                ],
                [
                  -122.057495827092,
                  37.3715860151634
                ],
                [
                  -122.057112227103,
                  37.3714618008523
                ]
              ]
            ]
          }
        }
      ],
      "landmarks": [
        {
          "place": {
            "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg",
            "displayName": {
              "text": "Chase Bank",
              "languageCode": "en"
            },
            "primaryType": "bank",
            "types": [
              "bank",
              "atm",
              "finance",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1234 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.373579,
              "longitude": -122.05752700000001
            }
          },
          "relationalDescription": {
            "text": "Near Chase Bank",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 61.182193756103516,
          "travelDistanceMeters": 63.075645446777344
        },
        {
          "place": {
            "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14",
            "displayName": {
              "text": "Safeway",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "butcher_shop",
              "florist",
              "deli",
              "supermarket",
              "bakery",
              "food_delivery",
              "market",
              "manufacturer",
              "food_store",
              "store",
              "food",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "639 S Bernardo Ave"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3727912,
              "longitude": -122.0581172
            }
          },
          "relationalDescription": {
            "text": "Around the corner from Safeway",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 158.65606689453125,
          "travelDistanceMeters": 131.1669921875
        },
        {
          "place": {
            "place": "places/ChIJu-PSYui2j4ARNiwOwBApGqk",
            "displayName": {
              "text": "Oil Changers",
              "languageCode": "en"
            },
            "types": [
              "car_repair",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Oil Changers, 1240 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1240 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3743054,
              "longitude": -122.0584272
            }
          },
          "relationalDescription": {
            "text": "Down the road from Oil Changers",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL"
          ],
          "straightLineDistanceMeters": 140.52459716796875,
          "travelDistanceMeters": 143.24220275878906
        },
        {
          "place": {
            "place": "places/ChIJKRbl5oG3j4ARwuvPGUmtCj0",
            "displayName": {
              "text": "Apni Mandi Farmers Market Sunnyvale",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "cake_shop",
              "supermarket",
              "asian_grocery_store",
              "indian_restaurant",
              "meal_takeaway",
              "bakery",
              "manufacturer",
              "wholesaler",
              "restaurant",
              "food_store",
              "store",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Apni Mandi Farmers Market Sunnyvale, 1111 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1056",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1111 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3737199,
              "longitude": -122.0522958
            }
          },
          "relationalDescription": {
            "text": "Near Apni Mandi Farmers Market Sunnyvale",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 410.37435913085938,
          "travelDistanceMeters": 479.49893188476562
        },
        {
          "place": {
            "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs",
            "displayName": {
              "text": "Starbird Chicken",
              "languageCode": "en"
            },
            "primaryType": "chicken_restaurant",
            "types": [
              "chicken_restaurant",
              "fast_food_restaurant",
              "restaurant",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1028",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1241 W El Camino Real"
              ]
            },
            "structureType": "BUILDING",
            "location": {
              "latitude": 37.3746764,
              "longitude": -122.05708860000001
            },
            "displayPolygon": {
              "coordinates": [
                [
                  [
                    -122.057003840785,
                    37.3747648209809
                  ],
                  [
                    -122.057136852459,
                    37.3747919153144
                  ],
                  [
                    -122.057205005705,
                    37.3745815131859
                  ],
                  [
                    -122.057071994114,
                    37.3745544186944
                  ],
                  [
                    -122.057003840785,
                    37.3747648209809
                  ]
                ]
              ],
              "type": "Polygon"
            }
          },
          "relationalDescription": {
            "text": "Near Starbird Chicken",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 87.348007202148438,
          "travelDistanceMeters": 214.08084106445312
        }
      ],
      "entrances": [
        {
          "location": {
            "latitude": 37.3735328,
            "longitude": -122.05694879999999
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJeMt61tqvQkARWT2716SDXsASEgljyy_n6LaPgBH9LoGUMNHjbBoSCWPLL-foto-AEf0ugZQw0eNsIhIJhf5y6ei2j4ARz7yBW5KAPI4",
          "location": {
            "latitude": 37.3738659,
            "longitude": -122.05693620000001
          },
          "travelModes": [
            "DRIVE",
            "WALK"
          ],
          "usages": [
            "PARKING"
          ]
        }
      ]
    }
  ]
}

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

אחת מ-3 האפשרויות הבאות צריכה להופיע בבקשת ה-API, שבה מצוינת הכתובת, המקום או המיקום לחיפוש יעד:
- ‫addressQuery – הכתובת לחיפוש.
- ‫place – מזהה המקום של המקום שרוצים לחפש.
- ‫locationQuery – קואורדינטות קו הרוחב וקו האורך של המיקום שרוצים לחפש.
FieldMask

כדי לציין את רשימת השדות שיוחזרו בתגובה, יוצרים מסכת שדות של תגובה. מעבירים את מסכת שדות התגובה לשיטה באמצעות פרמטר כתובת ה-URL‏ $fields או fields, או באמצעות כותרת ה-HTTP‏ X-Goog-FieldMask. לדוגמה, הבקשה הבאה תחזיר רק את הכניסות, נקודות הניווט ומזהה המקום של היעד הראשי.
```
  curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
    -H "X-Goog-Api-Key: API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary.place" \
    https://geocode.googleapis.com/v4beta/geocode/destinations
  
```
אין רשימת ברירת מחדל של שדות שמוחזרים בתגובה. אם לא מציינים את מסכת השדה, השיטה מחזירה שגיאה. מגדירים את מסכת השדות ל-* כדי להחזיר את כל השדות. פרטים נוספים מופיעים במאמר בנושא בחירת שדות להחזרה.

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

travelModes

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

השפה שבה יוחזרו התוצאות.
- כאן אפשר לעיין ברשימת השפות הנתמכות. ‫Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא מלאה.
- אם לא מציינים את הערך languageCode, ברירת המחדל של ה-API היא en. אם מציינים קוד שפה לא תקין, ה-API מחזיר שגיאה INVALID_ARGUMENT.
- ה-API עושה כמיטב יכולתו כדי לספק כתובת רחוב שקלה לקריאה גם למשתמש וגם לתושבים המקומיים. כדי להשיג את המטרה הזו, הוא מחזיר כתובות רחוב בשפה המקומית, בתעתיק לכתב שהמשתמש יכול לקרוא אם צריך, בהתאם לשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מתוך הרכיב הראשון.
- אם שם לא זמין בשפה המועדפת, ה-API משתמש בהתאמה הכי קרובה.
- לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שממשק ה-API בוחר להחזיר, ועל הסדר שבו התוצאות מוחזרות. הכלי להמרת כתובות לקואורדינטות (geocoder) מפרש קיצורים בצורה שונה בהתאם לשפה, כמו קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת.
regionCode

קוד האזור כערך של קוד CLDR באורך שני תווים. אין ערך ברירת מחדל. רוב הקודים של CLDR זהים לקודים של ISO 3166-1.
כשמבצעים המרה של כתובת לקואורדינטות (geocoding), המרת כתובות לקואורדינטות קדימה, הפרמטר הזה יכול להשפיע על התוצאות מהשירות, אבל לא להגביל אותן באופן מלא לאזור שצוין. כשממירים כתובת לקואורדינטות (geocoding) של מיקום או של מקום, המרת קואורדינטות לכתובת (reverse geocoding) או המרת קואורדינטות לכתובת של מקום, אפשר להשתמש בפרמטר הזה כדי לעצב את הכתובת. בכל המקרים, הפרמטר הזה יכול להשפיע על התוצאות בהתאם לדין החל.
placeFilter

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

סינון לפי רמת פירוט מבנית

המסנן structureType מאפשר לציין את סוגי המבנים שמוחזרים על ידי השאילתה:
- בידוד בניינים: אפשר להשתמש ב-"structureType": "BUILDING" כדי להציג קווי מתאר של בניין במפה או לקבל פרטים על מבנה ספציפי.
- הסבר על מתחמים: משתמשים ב-"structureType": "GROUNDS" כדי לוודא שהתוצאה העיקרית היא השטח הכולל. האפשרות הזו שימושית כשמבצעים שאילתות לגבי אזורים גדולים יותר, כמו קמפוסים או מרכזי קניות.
- התמקדות ביחידות או בקטעים: אפשר להשתמש ב-"structureType": "SECTION" כדי לזהות קטעים בתוך בניין.
איך מוודאים שהכתובות שימושיות

לא לכל המקומות יש כתובות ברורות ברמת הרחוב. המסנן addressability עוזר לכם לשלוט באיכות הכתובות בתוצאות:
- חובה לציין כתובת ראשית ברורה: כדי לוודא שתוצאת היעד הראשית תמיד תכלול כתובת או שם ברמת הרחוב, משתמשים ב-"addressability": "PRIMARY". האפשרות הזו שימושית למטרות ניווט או הצגה, שבהן חשוב להציג כתובת ברורה.
- התרת כתובות ביעדי משנה: במקרים שבהם למקום הראשי אין כתובת, אבל ליחידות בתוכו יש כתובת (למשל, דירות בבניין), "addressability": "WEAK" מוודא שלפחות למקום הראשי או לאחד מיעדי המשנה שלו יש כתובת.
- כל תוצאה: אם נוכחות הכתובת לא רלוונטית לתרחיש השימוש שלכם, השתמשו בערך "addressability": "ANY".
דוגמה: סינון לפי בניינים שאפשר להציג בהם מודעות
```
curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "PRIMARY"
    }
  },
  "languageCode": "en"
}' \\
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\
-H "X-Goog-FieldMask: place" \\
https://geocode.googleapis.com/v4beta/geocode/destinations
```

משוב

זוהי נקודת קצה ניסיונית של Geocoding API. נשמח לקבל משוב בכתובת geocoding-feedback-channel@google.com.

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

בקשה לחיפוש יעדים

חיפוש יעד לפי כתובת

חיפוש יעד לפי מזהה מקום

מזהי מקומות נתמכים

חיפוש יעד לפי מיקום

שימוש ב-OAuth כדי לשלוח בקשה

תגובה של חיפוש יעדים

primary

containingPlaces

subDestinations

entrances

structureType

navigationPoints

arrivalSummary

landmarks

פורמט התשובה

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

FieldMask

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

travelModes

languageCode

regionCode

placeFilter

סינון לפי רמת פירוט מבנית

איך מוודאים שהכתובות שימושיות