تبلغ الحصة التلقائية لطُرق 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

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

تعمل طريقة Search 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`

مصفوفة من عناصر PlaceView تمثّل كيانات مكانية أكبر تحيط بالوجهة الأساسية أو تحتوي عليها على سبيل المثال:

إذا كانت الوجهة الأساسية متجرًا أو مطعمًا داخل مركز تسوّق، يتضمّن containingPlaces مركز التسوّق (structureType: GROUNDS).
إذا كانت الوجهة الأساسية هي شقة سكنية فردية (subpremise)، يتضمّن containingPlaces المبنى السكني المحيط (structureType: BUILDING) ومجمّع الشقق الأوسع (structureType: GROUNDS)، إن توفّر.

يتضمّن كل PlaceView في containingPlaces سمات displayName وplaceId وlocation وstructureType وdisplayPolygon (عند توفّرها)، ما يتيح لك عرض المخطط التفصيلي الكامل للمجمّع أو المبنى إلى جانب الوحدة المحدّدة.

`subDestinations`

مصفوفة من عناصر PlaceView تمثّل مواقع جغرافية أكثر دقة ضمن الوجهة الأساسية على سبيل المثال:

عند البحث عن مركز تسوّق أو مطار أو حرم جامعي، يعرض subDestinations المتاجر الفردية أو المحطات أو البوابات أو مباني الحرم الجامعي.
عند الاستعلام عن مبنى سكني أو تجاري متعدّد الوحدات، يعرض subDestinations أجنحة أو شققًا فردية.

يمكنك استخدام containingPlaces وsubDestinations معًا لإنشاء أدوات اختيار هرمية تفاعلية تساعد المستخدمين في توضيح مواقع الوصول المعقّدة.

التسلسل الهرمي للوجهات وسلوك الاستجابة

عند تفسير استجابة Destination، ضع في اعتبارك القواعد والعلاقات الهيكلية التالية:

primary: يمثّل الكيان الأكثر تحديدًا الذي تم العثور عليه لطلب البحث (مثل مبنى أو مبنى فرعي). ويتم ملء هذا الحقل في معظم حالات الاستخدام العادية. ومع ذلك، في المناطق الريفية، من الممكن أن تفتقر الوجهة إلى كيان أساسي مع استمرار وجود نقاط تنقّل أو معالم.
يمثّل الحقل containingPlaces الأماكن الرئيسية المحيطة (الأماكن السابقة): تتم تعبئة الحقل containingPlaces عندما يكون المكان الأساسي مضمّنًا فعليًا داخل هياكل مكانية أكبر. بالنسبة إلى الأماكن الأكثر دقة، مثل مبنى فرعي، يمكن أن يعرض جميع مستويات الأماكن الرئيسية في التسلسل الهرمي. ويمكن أن يشمل ذلك أقسام المبنى المغلقة وBUILDING والمجمّع أو المجمّع السكني GROUNDS. إذا كانت الوجهة عبارة عن مبنى مستقل أو دبوس معزول، قد يكون الحقل containingPlaces فارغًا.
‫subDestinations تمثّل الأماكن الفرعية المضمّنة (الأماكن التابعة): تتم تعبئة السمة subDestinations عندما تتضمّن الوجهة أماكن أكثر دقة، ويمكن أن تشمل أنواعًا مختلفة من بنية الأماكن التابعة، مثل BUILDING في حرم جامعي أو أراضٍ، أو وحدات داخلية وأقسام ومتاجر داخل مبنى.

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

مصفوفة من عناصر Landmark تمثّل الأماكن البارزة المجاورة التي تساعد المستخدمين في توجيه أنفسهم وتحديد موقع الوجهة عند الوصول. تحلّ هذه الإمكانية محلّ ميزة "أوصاف العناوين" القديمة في الإصدار 3 وتوسّع نطاقها.

يحتوي كل عنصر Landmark على ما يلي:

‫place: عنصر PlaceView يصف المعلم، بما في ذلك displayName وplaceId وlocation وtypes وdisplayPolygon.
‫relationalDescription: سلسلة LocalizedText مترجَمة ويمكن لشخص عادي قراءتها تصف العلاقة المكانية بين الوجهة والمعلم (على سبيل المثال، "Near Starbird Chicken" أو "Across from Central Park" أو "Around the corner from the Empire State Building").
‫straightLineDistanceMeters: المسافة في خط مستقيم (المسافة الجوية) بالأمتار من المَعلم إلى الوجهة
‫travelDistanceMeters: مسافة السفر المقدَّرة بالأمتار على طول الطريق أو شبكة المشاة بين المَعلم والوجهة
‫tags: علامات سياقية تشير إلى الدور المكاني للمعلم بالنسبة إلى الوجهة:
- ‫"ARRIVAL": معلم محلي صغير مجاور للوجهة مباشرةً أو مقابلها (عادةً في نطاق يتراوح بين 50 و100 متر)، وهو الأفضل للحصول على إرشادات الوصول إلى الوجهة النهائية.
- ‫"ADDRESS": مَعلم بارز محليًا في الحي المحيط (عادةً على بُعد يتراوح بين 100 و500 متر)، وهو الأفضل للتوجيه قبل الرحلة وتأكيد العنوان.
- يمكن أن تحتوي المعالم على كلتا العلامتَين إذا كانت بارزة محليًا ومجاورة مباشرةً.

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

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

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

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

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

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

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

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

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

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

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

primary

addressComponents

containingPlaces

subDestinations

التسلسل الهرمي للوجهات وسلوك الاستجابة

entrances

structureType

navigationPoints

landmarks

arrivalSummary

parkingOptions

تنسيق الردّ

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

FieldMask

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

travelModes

languageCode

regionCode

placeFilter

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

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