تبلغ الحصة التلقائية لطُرق Geocoding API v4‏ 25 طلب بحث في الثانية (QPS). للحصول على معلومات حول طلب حصة أعلى، يُرجى الاطّلاع على عرض الحصص وإدارتها واختيار Geocoding API كخدمة.

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

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

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

يشير 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 شارع الرئيسي") أو أقسام من مسار بدون رقم محدّد أو رموز المواقع المفتوحة. لا تتوفّر أيضًا معرّفات الأماكن للنتائج التي تغطي مساحة كبيرة جدًا (مثل "المحيط الهادئ").

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

لضمان التوافق، استخدِم الإكمال التلقائي (جديد) للعثور على معرّفات الأماكن التي يمكن استخدامها مع "وجهات البحث". عند استخدام ميزة "الإكمال التلقائي (جديدة)"، عليك فلترة النتائج حسب النوع باستخدام المَعلمة 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 ضِمن استجابة Search Destinations (مثل primary والعناصر في containingPlaces وlandmarks) حقولاً للإشارة إلى نوع المكان:

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

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

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

`primary`

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

`addressComponents`

مصفوفة تحتوي على المكوّنات المنفصلة التي تنطبق على هذا العنوان.

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

‫types[] هي مصفوفة تشير إلى نوع مكوّن العنوان. اطّلِع على قائمة الأنواع المتوافقة.
‫longText هو الوصف النصي الكامل أو اسم مكوّن العنوان كما يعرضه Geocoder.
‫shortText هو اسم نصي مختصر لمكوّن العنوان، إذا كان متاحًا. على سبيل المثال، قد يتضمّن أحد مكونات العنوان الخاص بولاية ألاسكا longText بقيمة "ألاسكا" وshortText بقيمة "AK" باستخدام الاختصار البريدي المكوّن من حرفين.
‫languageCode هي اللغة المستخدَمة لتنسيق هذا المكوّن، وذلك باستخدام ترميز CLDR.

`containingPlaces`

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

`subDestinations`

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

`entrances`

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

location

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

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

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

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

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

`structureType`

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

POINT

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

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

مبنى
GROUNDS

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

`navigationPoints`

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

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

navigationPointToken هو رمز مميّز يحتوي على المعلومات السياقية في الحقل navigationPoints. يمكنك إرسال الرمز المميّز هذا إلى واجهات برمجة التطبيقات الخاصة بتحديد أفضل مسار والتنقّل لتحسين تجربة تحديد أفضل مسار والتنقّل في تطبيقك. لمزيد من المعلومات، راجِع التوجيه باستخدام الرموز المميّزة لنقاط التنقّل.
يحتوي 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`

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

`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
```

البحث عن الوجهات تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

البحث عن وجهة باستخدام معرّف المكان

أرقام تعريف الأماكن المتوافقة

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

البحث عن وجهة حسب الموقع الجغرافي

استخدام OAuth لتقديم طلب

ردّ البحث عن الوجهات

primary

addressComponents

containingPlaces

subDestinations

entrances

structureType

navigationPoints

landmarks

arrivalSummary

parkingOptions

تنسيق الردّ

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

FieldMask

المعلمات الاختيارية

travelModes

languageCode

regionCode

placeFilter

الفلترة حسب مستوى التفاصيل البنيوية

ضمان توفّر عناوين مفيدة