تبلغ الحصة التلقائية لطُرق 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"
عدد كبير جدًا من المفاهيم أو القيود، مثل أسماء أماكن أو طرق أو مدن متعددة في طلب بحث واحد	"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.

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

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

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

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

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

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

`primary`

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

`addressComponents`

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

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

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

`containingPlaces`

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

`subDestinations`

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

`entrances`

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

displayName

تمثّل هذه السمة عنصر LocalizedText يحتوي على اسم يمكن لشخص عادي قراءته للمدخل (على سبيل المثال، "South Bernardo Avenue" أو "5th Avenue")، إذا كان متاحًا.
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`

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

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

‫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": [
        {
          "displayName": {
            "text": "South Bernardo Avenue",
            "languageCode": "en"
          },
          "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
```
الجهد

ميزة تجريبية: المَعلمة effort هي ميزة تجريبية. يمكنك إنشاء طلبات HTTP باستخدام قناة /v4alpha/. مزيد من المعلومات حول قنوات مراحل الإطلاق

تحدّد مقدار المعالجة Effort التي يجب تطبيقها عند حلّ طلب البحث عن الوجهة (تؤثر بشكل أساسي في addressQuery الحلّ):
- ‫EFFORT_UNSPECIFIED: القيمة التلقائية يعمل بالطريقة نفسها التي يعمل بها جهد LOW.
- ‫LOW: لتحسين أوقات الاستجابة لتكون الأسرع لا يتم إجراء بحث موسّع أو توضيح للعناوين الصعبة.
- ‫MEDIUM: يوازن بين السرعة والدقة. تتم الاستجابة لمعظم الطلبات بوقت استجابة عادي وسريع. بالنسبة إلى العناوين الغامضة أو الصعبة، تطبّق الخدمة معالجة إضافية لتحسين الدقة، وقد يستغرق ذلك بضع ثوانٍ. يُنصح به لمهام سير العمل التفاعلية التي يمكن للمستخدمين فيها تحمُّل توقُّف مؤقت قصير.
- HIGH — تزيد من دقة تحليل العناوين غير المكتملة أو غير الرسمية أو المعقدة. قد يستغرق الردّ وقتًا أطول بكثير. يُنصح به لسير عمل الإرسال في الخلفية أو الدفعات أو الخدمات اللوجستية.
على سبيل المثال، يستخدم الطلب التالي "effort": "HIGH" لحلّ طلب بحث عن عنوان وجهة:
```
curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai"
  },
  "effort": "HIGH"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
```
لمزيد من التفاصيل حول توقّعات وقت الاستجابة وحدود المعدّل وأنماط الدمج المقترَحة، يُرجى الاطّلاع على الترميز الجغرافي بدقة محسّنة.

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

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

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

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

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

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

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

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

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

primary

addressComponents

containingPlaces

subDestinations

entrances

structureType

navigationPoints

landmarks

arrivalSummary

parkingOptions

تنسيق الردّ

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

FieldMask

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

travelModes

languageCode

regionCode

placeFilter

الفلترة حسب دقة البنية

التأكّد من أنّ العناوين مفيدة

الجهد