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

לחפש יעדים

מפתחים באזור הכלכלי האירופי (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"
שאילתות דו-משמעיות עם כמה פרשנויות	"החזרת מטען"
שמות היסטוריים שכבר לא נמצאים בשימוש	"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

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

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

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

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

"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 מספקת הקשר עשיר ומקומי מאוד לגבי המיקום.

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

`primary`

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

`containingPlaces`

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

`subDestinations`

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

`entrances`

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

location

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

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

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

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

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

travelModes

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

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

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

arrivalSummary

landmarks

פורמט התשובה

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

FieldMask

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

travelModes

languageCode

regionCode

placeFilter

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

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