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

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

يشير 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"
عدد كبير جدًا من المفاهيم أو القيود، مثل أسماء أماكن أو طرق أو مدن متعددة في طلب بحث واحد "Market Street San Francisco San Jose Airport"
عناصر العنوان البريدي غير الممثّلة على "خرائط Google" "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"
أسماء الأنشطة التجارية أو السلاسل أو الفئات المدمجة مع المواقع الجغرافية التي لا تتوفّر فيها هذه الكيانات "Tesco بالقرب من دالاس، تكساس"
طلبات البحث الغامضة التي تحتمل تفسيرات متعددة "تسليم الشاحن"
الأسماء السابقة التي لم تعُد مستخدَمة "Middlesex United Kingdom"
عناصر أو نية غير مرتبطة بالموقع الجغرافي "كم عدد القوارب في ميناء فينتورا؟"
الأسماء غير الرسمية أو المخصّصة "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

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

تعمل طريقة "البحث عن الوجهات" بشكل أفضل مع أرقام تعريف الأماكن التي تمثّل وجهات محدّدة يمكن التنقّل إليها. تتوفّر بشكل عام أرقام تعريف الأماكن لأنواع مثل establishment وpoint_of_interest وpremise وstreet_address وsubpremise. لا تتوافق أرقام تعريف الأماكن التي لا تمثّل مواقع جغرافية منفصلة، مثل تلك التي يتم استنتاجها من نطاقات العناوين (على سبيل المثال، "10-20 شارع رئيسي") أو أقسام المسار بدون رقم محدّد أو رموز Plus Codes. لا تتوافق أيضًا أرقام تعريف الأماكن الخاصة بالنتائج التي تغطي مساحة كبيرة جدًا (مثل "المحيط الهادئ").

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

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

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

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

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

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

landmarks

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

يحتوي كل مَعلم على الحقول التالية:

  • ‫place هو عنصر PlaceView الذي يمثّل هذا المَعلم.
  • ‫relationalDescription هو وصف يمكن لشخص عادي قراءته لكيفية ارتباط الوجهة بالمعلم، مثل "بالقرب من برج خليفة" أو "مقابل البيت الأبيض".
  • ‫tags[] هي مجموعة من العلامات التي توضّح كيفية استخدام المعلم في سياق الوجهة:
    • "ADDRESS": مكان بارز محليًا يمكن استخدامه لتحديد الموقع الجغرافي العام للوجهة
    • ‫"ARRIVAL": مكان يمكن استخدامه للمساعدة في الوصول إلى الوجهة، وهو مفيد للتنقّل عند الاقتراب من الوجهة.
  • ‫straightLineDistanceMeters هي المسافة في خط مستقيم من هذا المعلم إلى الوجهة بالأمتار.
  • ‫travelDistanceMeters هي المسافة سيرًا على الأقدام من هذا المعلم إلى الوجهة بالأمتار.

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