البحث عن الوجهات

المطوّرون في المنطقة الاقتصادية الأوروبية

يشير 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

يمكنك تحديد الموقع الجغرافي للبحث عن وجهة بإحدى الطرق الثلاث التالية:

  • العنوان
  • معرّف المكان
  • إحداثيات خطوط العرض وخطوط الطول

البحث عن وجهة حسب العنوان

يمكنك تحديد العنوان كسلسلة غير منظَّمة، ولكن لا تحلّل خدمة الترميز الجغرافي للعناوين إحداثيات خطوط الطول والعرض أو السلاسل غير المنظَّمة الأخرى التي لا تمثّل عنوانًا. لا تتوافق الطلبات التي تستخدم مثل هذه السلاسل، وقد تؤدي إلى ظهور ردود تتضمّن أخطاء أو سلوك غير محدّد. تشمل الأمثلة على طلبات البحث غير المتوافقة ما يلي:

نوع طلب البحث مثال
إحداثيات خط العرض وخط الطول استخدِم طلب بحث عن موقع جغرافي بدلاً من ذلك. "37.422131,-122.084801"
عدد كبير جدًا من المفاهيم أو القيود، مثل أسماء أماكن أو طرق أو مدن متعددة في طلب بحث واحد "شارع ماركت في سان فرانسيسكو، مطار سان خوسيه"
عناصر العنوان البريدي غير الممثّلة على "خرائط Google" "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"
أسماء الأنشطة التجارية أو السلاسل أو الفئات مع المواقع الجغرافية التي لا تتوفّر فيها هذه الكيانات "Tesco بالقرب من دالاس، تكساس"
طلبات بحث غامضة تتضمّن تفسيرات متعددة "استلام الشاحن"
الأسماء القديمة التي لم يعُد يتم استخدامها "ميدلسكس، المملكة المتحدة"
العناصر أو النية غير الجغرافية المكانية "كم عدد القوارب في ميناء فينتورا؟"
الأسماء غير الرسمية أو أسماء الشهرة "The Jenga"
"The Helter Skelter"
الكيانات السياسية الكبيرة (المدن والولايات والبلدان) "مدينة نيويورك"
"كاليفورنيا"
"الولايات المتحدة الأمريكية"
المسارات التي لا تتضمّن عناوين محدّدة "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") أو أقسام من مسار بدون رقم محدّد أو رموز المواقع المفتوحة. لا تتوافق أيضًا معرّفات الأماكن الخاصة بالنتائج التي تغطي مساحة كبيرة جدًا (مثل "المحيط الهادئ").

استخدام ميزة "الإكمال التلقائي" في Places API (الجديدة) مع ميزة "البحث عن الوجهات"

لضمان التوافق، استخدِم 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 لتقديم طلب

تتيح الإصدار 4 من Geocoding API استخدام 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.

ردّ البحث في الوجهات

تقدّم استجابة "وجهات البحث" سياقًا غنيًا وعلى مستوى منطقة محلية صغيرة حول الموقع الجغرافي.

تستخدم عناصر PlaceView ضمن استجابة "وجهات البحث" (مثل primary والعناصر في containingPlaces وlandmarks) حقولاً للإشارة إلى نوع المكان:

  • types: مصفوفة من السلاسل تشير إلى أنواع المكان.
  • primaryType: سلسلة تشير إلى النوع الأساسي للمكان.

يتم استخلاص قيم السلسلة المحتملة لكلّ من types وprimaryType من الجدول A والجدول B في صفحة "أنواع الأماكن (جديد)".

يوضّح هذا القسم حقول الرد الرئيسية. وللحصول على تفاصيل كاملة عن جميع حقول الرد، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات.

primary

المكان الرئيسي الذي يحدّده طلب البحث في الطلب.

containingPlaces

الكيانات الأكبر التي يشكّل الوجهة الأساسية جزءًا منها (على سبيل المثال، مركز تسوّق يضم متجرًا)

subDestinations

مواقع جغرافية أكثر تحديدًا ضمن الوجهة الأساسية (على سبيل المثال، شقق في مبنى)

entrances

تحتوي العناصر في مصفوفة entrances[] على الحقول التالية:

  • location

    زوج إحداثيات خط العرض وخط الطول الفردي الذي يحدّد موقع نقطة الدخول والخروج من مكان

  • entrance_tags[]

    مصفوفة من علامات الدخول التي تصف خصائص المدخل. القيمة التالية مسموح بها:

    • "PREFERRED"

    تشير إلى أنّ هذا المدخل يوفّر على الأرجح إمكانية الوصول إلى المكان المعروض. يمكن أن يكون للمكان عدة مداخل مفضّلة. إذا لم يتضمّن المدخل هذه العلامة، يعني ذلك أنّ المدخل يقع في المبنى نفسه، ولكنّه لا يتيح بالضرورة الوصول إلى المكان.

    على سبيل المثال، إذا كان المكان الذي تم عرضه هو مطعم في قطاع مركز تجاري، ستكون "PREFERRED" المداخل هي تلك التي تؤدي إلى المطعم نفسه، بينما ستكون المداخل الأخرى التي تم عرضها هي مداخل أخرى للمبنى، مثل المداخل المؤدية إلى مطاعم أخرى في قطاع المركز التجاري.

    إذا كان المكان الذي تم عرضه هو مبنى، ستكون مداخل "PREFERRED" هي تلك التي تؤدي إلى الجزء "الرئيسي" من المبنى. على سبيل المثال، في مركز تسوّق، ستكون "PREFERRED" المداخل هي تلك التي تتيح الوصول إلى منطقة البهو الرئيسية، ولكن إذا كان أحد المداخل يتيح الوصول إلى متجر على جانب المبنى فقط، فلن يكون "PREFERRED" مدخلاً.

  • streetViewThumbnail وstreetViewAnnotation

    مَعلمات Street View Static API التي تتيح لك عرض صور ذات صلة بهذه المواقع الجغرافية مزيد من المعلومات حول هذه الحقول

structureType

تمثّل هذه السمة نوع البنية التي يمثّلها هذا المكان.

  • POINT

    موقع جغرافي على شكل نقطة

  • SECTION

    قسم فرعي من مبنى

  • BUILDING

    مبنى

  • GROUNDS

    مساحة كبيرة تحتوي عادةً على مبانٍ متعددة، مثل حرم جامعي أو مجمّع سكني أو مركز تسوّق

يحتوي الحقل navigationPoints ضمن استجابة الترميز الجغرافي على قائمة بنقاط مفيدة للتنقّل إلى المكان. على وجه التحديد، يجب استخدامها كنقاط بداية أو نهاية عند تحديد المسار على شبكة طرق من المكان أو إليه.

تحتوي كل نقطة تنقّل على القيم التالية:

  • navigationPointToken هو رمز مميّز يحتوي على المعلومات السياقية في الحقل navigationPoints. يمكنك إرسال هذا الرمز المميّز إلى واجهات برمجة التطبيقات الخاصة بالتوجيه والتنقّل لتحسين تجربة التوجيه والتنقّل في الأنهار داخل تطبيقك. لمزيد من المعلومات، راجِع التوجيه باستخدام الرموز المميّزة لنقاط التنقّل.
  • يحتوي location على قيمة خط العرض وخط الطول لنقطة التنقّل. سيكون هذا الموقع الجغرافي دائمًا قريبًا جدًا من شبكة الطرق ويمثّل نقطة توقّف أو نقطة البداية مثالية للتنقّل من مكان وإليه. يتم إزاحة النقطة قليلاً عن خط المنتصف للطريق بشكل متعمّد لتحديد الجانب الذي يقع فيه المكان بوضوح.
  • travelModes هي قائمة بوسائل النقل التي يمكن الوصول إلى نقطة التنقّل منها:
    • "DRIVE" هو وضع السفر الذي يتوافق مع اتجاهات القيادة.
    • "WALK" هي وسيلة النقل التي تتوافق مع اتّجاهات المشي.
  • usages هي قائمة بالاستخدامات التي تتيحها نقطة التنقّل. يمكن أن تكون الاستخدامات:
    • "DROPOFF"
    • "PICKUP"
    • "PARKING"

بالنسبة إلى نقاط الاستلام والتسليم، استخدِم نقطة التنقّل التي تكون فيها وسيلة النقل DRIVE والاستخدام PICKUP أو DROPOFF. وإذا لم تتوفّر نقاط الاستلام أو التسليم، استخدِم نقطة التنقّل الأعلى للتنقل بالسيارة.

  • يمثّل altitude_meters ارتفاع نقطة التنقّل بالأمتار بالنسبة إلى مجسم WGS-84 الناقص. في الحالات التي تتضمّن أجزاء طرق مكدّسة عموديًا، استخدِم الحقل altitude_meters لاختيار أفضل جزء طريق يمكن لنظامك التنقّل إليه.

landmarks

أماكن بارزة قريبة لمساعدة المستخدمين في فهم المناطق المحيطة بالوجهة

arrivalSummary

إحصاءات مستندة إلى الذكاء الاصطناعي للمساعدة في الوصول إلى الوجهة ملخّصات مستنِدة إلى الذكاء الاصطناعي

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"
          ]
        }
      ]
    }
  ]
}

المعلمات المطلوبة

  • يجب أن تتضمّن طلب البيانات من واجهة برمجة التطبيقات إحدى المَعلمات الثلاث التالية التي تحدّد العنوان أو المكان أو الموقع الجغرافي المطلوب البحث عن وجهة فيه:
    • 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، تضبط واجهة برمجة التطبيقات القيمة التلقائية على en. إذا حدّدت رمز لغة غير صالح، ستعرض واجهة برمجة التطبيقات رسالة الخطأ INVALID_ARGUMENT.
    • تبذل واجهة برمجة التطبيقات قصارى جهدها لتوفير عنوان شارع يمكن قراءته من قِبل المستخدمين والسكان المحليين. لتحقيق هذا الهدف، تعرض الخدمة عناوين الشوارع باللغة المحلية، مع ترجمتها إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكونات العنوان باللغة نفسها، والتي يتم اختيارها من المكون الأول.
    • إذا لم يتوفّر اسم باللغة المفضّلة، تستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابِقة.
    • للغة المفضّلة تأثير بسيط على مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وعلى ترتيب عرضها. يفسّر برنامج الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة ما ولكن ليس في لغة أخرى.
  • regionCode

    تمثّل هذه السمة رمز المنطقة كقيمة رمز CLDR مكوّن من حرفَين، ولا تتضمّن قيمة تلقائية. تتطابق معظم رموز CLDR مع رموز ISO 3166-1.

    عند الترميز الجغرافي لعنوان، أي الترميز الجغرافي المباشر، يمكن أن تؤثّر هذه المَعلمة في النتائج التي تقدّمها الخدمة في المنطقة المحدّدة، ولكن لا يمكنها حصرها بالكامل. وعند الترميز الجغرافي لموقع جغرافي أو مكان، أي الترميز الجغرافي العكسي أو الترميز الجغرافي للمكان، يمكن استخدام هذه المَعلمة لتنسيق العنوان. وفي جميع الحالات، يمكن أن تؤثّر هذه المَعلمة في النتائج استنادًا إلى القانون الساري.

  • 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