לשיטות של Geocoding API v4 מוגדרת כברירת מחדל מכסה של 25 שאילתות לשנייה (QPS). מידע על בקשה להגדלת המכסה זמין במאמר איך רואים ומנהלים את המכסות. צריך לבחור באפשרות Geocoding API כשירות.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

לחפש יעדים

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

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

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

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

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

https://geocode.googleapis.com/v4/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/v4/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/v4/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/v4/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/v4/geocode/destinations

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

השיטה Search Destinations (חיפוש יעדים) מתאימה במיוחד למזהי מקומות שמייצגים יעדים ספציפיים שאפשר לנווט אליהם. בדרך כלל יש תמיכה במזהי מקומות מסוגים כמו establishment,‏ point_of_interest,‏ premise,‏ street_address ו-subpremise. אין תמיכה במזהי מקומות שלא מייצגים מיקומים נפרדים, כמו מזהי מקומות שמשתמעים מטווחים של כתובות (לדוגמה, '10-20 Main St'), מקטעים של מסלול ללא מספר ספציפי או קודי פלוס. אין תמיכה גם במזהי מקומות של תוצאות ששטחן גדול מדי (לדוגמה, 'האוקיינוס השקט').

שימוש ב-Places API Autocomplete (חדש) עם 'חיפוש יעדים'

כדי לוודא תאימות, צריך להשתמש ב-Places API Autocomplete (חדש) כדי למצוא מזהי מקומות לשימוש עם 'חיפוש יעדים'. כשמשתמשים ב-Autocomplete, צריך לסנן את התוצאות לפי סוג באמצעות הפרמטר includedPrimaryTypes. מזהי מקומות שמוחזרים על ידי Autocomplete באמצעות המסנן המומלץ הבא נתמכים על ידי 'חיפוש יעדים':

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

בנוסף, לא מומלץ להגדיר את הדגל include_pure_service_area_businesses לערך true בבקשה להשלמה אוטומטית.

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

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

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/v4/geocode/destinations

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

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

https://www.googleapis.com/auth/maps-platform.geocode ‫— לשימוש בכל ה-methods של Geocoding API.

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

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

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

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

אובייקטים מסוג PlaceView בתגובה של Search Destinations (כמו primary, פריטים ב-containingPlaces ו-landmarks) משתמשים בשדות כדי לציין את סוג המקום:

‫types: מערך של מחרוזות שמציין את סוגי המקום.
‫primaryType: מחרוזת שמציינת את הסוג העיקרי של המקום.

הערכים האפשריים של המחרוזות עבור types ו-primaryType מופיעים בטבלה א' ובטבלה ב' בדף 'סוגי מקומות (חדש)'.

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

`primary`

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

`containingPlaces`

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

`subDestinations`

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

`entrances`

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

location

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

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

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

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

פרמטרים של Street View Static API, שמאפשרים להציג תמונות רלוונטיות של המיקומים האלה. מידע נוסף על השדות האלה

`structureType`

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

POINT

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

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

בניין.
GROUNDS

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

`navigationPoints`

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

כל נקודת ניווט מכילה את הערכים הבאים:

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

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

‫streetViewThumbnail ו-entranceAnnotation מספקים פרמטרים ל-Street View Static API, שמאפשרים לכם להציג תמונות רלוונטיות של המיקומים האלה. מידע נוסף על השדות האלה

‫altitude_meters מכיל את הגובה של נקודת הניווט במטרים ביחס לאליפסואיד WGS-84. במקרים שבהם יש מקטעי כביש שמוערמים אנכית, צריך להשתמש בשדה altitude_meters כדי לבחור את מקטע הכביש הטוב ביותר שהמערכת יכולה לנווט אליו.

`landmarks`

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

`arrivalSummary`

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

`parkingOptions`

פרטים מפורטים על החניה.

פורמט התשובה

הפונקציה 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/v4/geocode/destinations
  
```
אין רשימת ברירת מחדל של שדות שמוחזרים בתגובה. אם משמיטים את מסיכת השדה, השיטה מחזירה שגיאה. כדי להחזיר את כל השדות, צריך להגדיר את מסכת השדות ל-*. פרטים נוספים זמינים במאמר בנושא בחירת השדות שיוחזרו.

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

travelModes

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

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

קוד האזור כערך קוד CLDR באורך שני תווים. אין ערך ברירת מחדל. רוב הקודים של CLDR זהים לקודים של ISO 3166-1.
כשמבצעים המרת כתובות לקואורדינטות (המרה גיאוגרפית קדימה), הפרמטר הזה יכול להשפיע על התוצאות מהשירות, אבל לא להגביל אותן באופן מלא לאזור שצוין. כשמבצעים המרת קואורדינטות לכתובות (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/v4/geocode/destinations
```

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

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

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

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

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

שימוש ב-Places API Autocomplete (חדש) עם 'חיפוש יעדים'

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

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

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

primary

containingPlaces

subDestinations

entrances

structureType

navigationPoints

landmarks

arrivalSummary

parkingOptions

פורמט התשובה

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

FieldMask

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

travelModes

languageCode

regionCode

placeFilter

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

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