- طلب HTTP
- نص الطلب
- نص الاستجابة
- نطاقات الأذونات
- SearchDestinationsRequest.AddressQuery
- SearchDestinationsRequest.LocationQuery
- SearchDestinationsRequest.LocationQuery.PlaceFilter
- PlaceView.StructureType
- SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability
- NavigationPoint.TravelMode
- الوجهة
- PlaceView
- PlaceView.AddressComponent
- المَعلم
- Landmark.Tag
- المدخل
- Entrance.Tag
- StreetViewThumbnail
- ImageAnnotation
- ImageAnnotation.Coordinate
- NavigationPoint
- NavigationPoint.Usage
- Destination.ParkingOptions
- Destination.ParkingOptions.Availability
- Destination.ArrivalSummary
تُجري هذه الطريقة عملية بحث عن وجهة وتعرض قائمة بالوجهات.
طلب HTTP
POST https://geocode.googleapis.com/v4alpha/geocode/destinations
يستخدِم عنوان URL بنية تحويل الترميز إلى gRPC.
نص الطلب
يتضمن نص الطلب بيانات بالبنية التالية:
| تمثيل JSON |
|---|
{ "travelModes": [ enum ( |
| الحقول | |
|---|---|
travelModes[] |
اختيارية: تمثّل هذه السمة وسائل النقل التي سيتم فلترة نقاط التنقّل وفقًا لها. يؤثر ذلك في الحقل |
languageCode |
اختيارية: اللغة التي يجب عرض النتائج بها |
regionCode |
اختيارية: رمز المنطقة رمز المنطقة، ويتم تحديده كقيمة مكوّنة من حرفَين ضمن ccTLD ("نطاق المستوى الأعلى"). تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري. تؤثّر هذه المَعلمة أيضًا في النتائج الواردة من الخدمة، ولكنّها لا تقيّدها بالكامل. |
حقل الربط يتم إنشاء الوجهات حول طلب البحث الأساسي المحدّد. ملاحظة: لا تتوفّر هذه الميزة إلا للأماكن والعناوين التي يمكن أن تكون وجهة للملاحة. على سبيل المثال، يمكن استخدام مكان يمثّل منزلاً أو مجمعًا سكنيًا كطلب بحث أساسي، ولكن لا يمكن استخدام أماكن تمثّل منطقة محلية أو منطقة إدارية كطلب بحث أساسي. يمكن أن يكون التعليق |
|
place |
اسم مصدر المكان، بالتنسيق |
addressQuery |
تمثّل هذه السمة عنوان الشارع. |
locationQuery |
موقع جغرافي دقيق |
نص الاستجابة
رسالة الردّ على DestinationService.SearchDestinations.
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
| تمثيل JSON |
|---|
{
"destinations": [
{
object ( |
| الحقول | |
|---|---|
destinations[] |
قائمة بالوجهات تعرض الخدمة نتيجة واحدة إذا كان من الممكن تحديد وجهة أساسية بشكل لا لبس فيه من طلب البحث الأساسي. وفي حال عدم توفّرها، قد تعرض الخدمة نتائج متعددة لإزالة الغموض أو لا تعرض أي نتائج. |
نطاقات الأذونات
يتطلب أحد نطاقات OAuth التالية:
https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/maps-platform.geocodehttps://www.googleapis.com/auth/maps-platform.destinations
SearchDestinationsRequest.AddressQuery
عنوان الشارع الذي تريد البحث عنه حدِّد العناوين وفقًا للتنسيق الذي تستخدمه خدمة البريد الوطنية في البلد المعنيّ.
| تمثيل JSON |
|---|
{ // Union field |
| الحقول | |
|---|---|
حقل الربط kind طلب البحث عن العنوان يمكن أن يكون التعليق kind إحدى القيم التالية فقط: |
|
address |
عنوان شارع بتنسيق عنوان بريدي |
addressQuery |
عنوان شارع منسَّق كسطر واحد |
SearchDestinationsRequest.LocationQuery
استعلام عن موقع جغرافي لتحديد وجهة أساسية قريبة
ملاحظة: إذا كان طلب البحث عن الموقع الجغرافي ضمن مبنى يحتوي على أماكن فرعية، من المحتمل أن يكون المكان الأساسي الذي تم عرضه مكانًا فرعيًا. وفي هذه الحالات، سيتضمّن الحقل containingPlaces المبنى.
| تمثيل JSON |
|---|
{ "placeFilter": { object ( |
| الحقول | |
|---|---|
placeFilter |
اختيارية: الفلاتر التي سيتم تطبيقها على الوجهات المرشّحة |
حقل الربط kind تمثّل هذه السمة طلب البحث عن الموقع الجغرافي. يمكن أن يكون التعليق kind إحدى القيم التالية فقط: |
|
location |
موقع جغرافي دقيق يحدّده خطّا العرض والطول |
SearchDestinationsRequest.LocationQuery.PlaceFilter
الفلاتر التي سيتم تطبيقها على المرشحين للوجهة
| تمثيل JSON |
|---|
{ "structureType": enum ( |
| الحقول | |
|---|---|
structureType |
اختيارية: في حال تحديد هذا النوع، سيتم ضمان توفّر مكان أساسي من هذا النوع في جميع الوجهات. يمكن أن يؤدي ذلك إلى فلترة بعض الوجهات أو إلى تقليل/زيادة دقة الوجهات التي يتم عرضها. على سبيل المثال، إذا تم تحديد ومن الاستخدامات الأخرى لهذا الحقل استخراج مضلّعات عرض المباني بسهولة أكبر. على سبيل المثال، إذا تم تحديد |
addressability |
اختيارية: في حال تحديدها، لا تعرض هذه السمة سوى الوجهات التي تستوفي معايير إمكانية الاستهداف ذات الصلة. |
PlaceView.StructureType
نوع البنية التي يمثّلها هذا المكان
| عمليات التعداد | |
|---|---|
STRUCTURE_TYPE_UNSPECIFIED |
غير مستخدَم |
POINT |
موقع جغرافي محدّد بنقطة |
SECTION |
جزء فرعي من مبنى |
BUILDING |
مبنى |
GROUNDS |
منطقة كبيرة تحتوي عادةً على مبانٍ متعددة، مثل حرم جامعي أو مجمّع سكني أو مركز تسوّق. |
SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability
تحدّد هذه السمة خيارات فلترة مدى توفّر الإعلانات. قد تتم إضافة قيم جديدة في المستقبل.
| عمليات التعداد | |
|---|---|
ADDRESSABILITY_UNSPECIFIED |
في حال عدم تحديدها، ستختار الخدمة قيمة تلقائية مناسبة. |
ANY |
لا يمكن استخدام إمكانية الوصول كمعيار فلترة. يتم عرض الوجهات بغض النظر عن إمكانية الوصول إليها. |
PRIMARY |
ستتضمّن جميع الوجهات التي يتم عرضها مكانًا أساسيًا يتضمّن عنوانًا أو اسمًا على مستوى الشارع. |
WEAK |
ستتضمّن جميع الوجهات التي يتم عرضها إما مكانًا أساسيًا أو وجهة فرعية مع عنوان أو اسم على مستوى الشارع. |
الوجهة
وجهة ويشمل ذلك المكان الأساسي والأماكن ذات الصلة والمداخل ونقاط التنقّل.
| تمثيل JSON |
|---|
{ "primary": { object ( |
| الحقول | |
|---|---|
primary |
المكان الأساسي الذي يحدّده |
containingPlaces[] |
الأماكن الأقل دقة التي يتضمّنها المكان الأساسي على سبيل المثال، المجمّع السكني الذي يضم هذا المبنى |
subDestinations[] |
وجهات فرعية أكثر دقة للمكان الأساسي على سبيل المثال، الوحدات الموجودة في مبنى. ملاحظة: بالمقارنة مع SubDestination التي تعرضها Places API، تكون قائمة الوجهات الفرعية هذه أكثر شمولاً، وتحتوي كل وجهة فرعية على المزيد من المعلومات. |
landmarks[] |
المعالم التي يمكن استخدامها لتحديد مكان الوجهة أو المساعدة في الوصول إليها |
entrances[] |
يشير هذا الحقل إلى مداخل الوجهة. |
navigationPoints[] |
نقاط التنقّل لهذه الوجهة |
parkingOptions |
خيارات مواقف السيارات في هذه الوجهة |
arrivalSummary |
ملخّص من إنشاء الذكاء الاصطناعي حول تجربة الوصول إلى الوجهة |
PlaceView
يمثّل عرضًا لمكان في Places API. وتوفّر أيضًا معلومات إضافية خاصة بالوجهات، مثل نوع البنية والمضلّع المعروض.
في بعض الحالات، قد يختلف PlaceView الذي يحمل رقم تعريف المكان نفسه عمّا تعرضه Places API للحقلَين types وdisplayName.
| تمثيل JSON |
|---|
{ "place": string, "displayName": { object ( |
| الحقول | |
|---|---|
place |
اسم المورد الخاص بهذا المكان، بالتنسيق |
placeId |
المعرّف الفريد لمكان معيّن |
displayName |
وصف المكان الذي يمكن لشخص عادي قراءته على سبيل المثال، "البوابة ب" أو "ماكدونالدز" |
primaryType |
تمثّل هذه السمة نوع المكان الأساسي. يمكنك الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/place-types للحصول على قائمة بالقيم المحتملة. ملاحظة: لا تتم تعبئة هذا الحقل دائمًا. يجب أن تكون مستعدًا لاستخدام الحقل |
types[] |
جميع أنواع الأماكن المرتبطة بهذا المكان يمكنك الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/place-types للحصول على قائمة بالقيم المحتملة. |
formattedAddress |
عنوان من سطر واحد |
postalAddress |
عنوان منظَّم |
structureType |
تمثّل هذه السمة نوع البنية التي يتضمّنها هذا المكان. |
location |
الموقع الجغرافي لهذا المكان بالنسبة إلى الأماكن التي تتضمّن مضلّعات عرض، يمكن أن يمثّل ذلك موضعًا جيدًا لوضع علامة على الخريطة. |
displayPolygon |
تمثّل هذه السمة المخطط التفصيلي للمضلّع الخاص بالمكان بتنسيق GeoJSON، باستخدام تنسيق RFC 7946: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6. ملاحظة: يتيح تنسيق RFC 7946 استخدام MultiPolygons، لذا يمكن أن يمثّل عنصر |
addressComponents[] |
مكوّنات متكرّرة لكل مستوى منطقة محلية |
PlaceView.AddressComponent
المكوّنات المنظَّمة التي تشكّل العنوان المنسَّق، إذا كانت هذه المعلومات متاحة
| تمثيل JSON |
|---|
{ "longText": string, "shortText": string, "types": [ string ], "languageCode": string } |
| الحقول | |
|---|---|
longText |
تمثّل هذه السمة الوصف النصي الكامل أو اسم مكوّن العنوان. على سبيل المثال، قد يكون الاسم الطويل لمكوّن العنوان الخاص ببلد أستراليا هو "أستراليا". |
shortText |
اسم نصي مختصر لمكوّن العنوان، إذا كان متاحًا على سبيل المثال، قد يتضمّن أحد عناصر العنوان الخاص ببلد أستراليا اسمًا مختصرًا هو "AU". |
types[] |
مصفوفة تشير إلى أنواع مكوّن العنوان. يُرجى الاطّلاع على https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types لمزيد من التفاصيل. |
languageCode |
اللغة المستخدَمة لتنسيق هذا المكوّن، بتنسيق CLDR |
مَعلم
تُستخدَم المعالم للإشارة إلى مكان الوجهة أو المساعدة في الوصول إليها.
| تمثيل JSON |
|---|
{ "relationalDescription": { object ( |
| الحقول | |
|---|---|
relationalDescription |
وصف يمكن لشخص عادي قراءته يوضح مدى صلة الوجهة بالمعلم على سبيل المثال: "بالقرب من مبنى إمباير ستيت" أو "مقابل البيت الأبيض". |
tags[] |
علامات تصف كيفية استخدام المعلم في سياق الوجهة. |
straightLineDistanceMeters |
النتائج فقط. المسافة في خط مستقيم من هذا المَعلم إلى الوجهة بالأمتار |
travelDistanceMeters |
النتائج فقط. المسافة سيرًا على الأقدام من هذا المعلم إلى الوجهة بالأمتار |
حقل الربط landmark المَعلم يمكن أن يكون التعليق landmark إحدى القيم التالية فقط: |
|
place |
تمثّل هذه السمة المكان الذي يقع فيه هذا المعلم. |
Landmark.Tag
قائمة بجميع العلامات المحتملة التي تصف كيفية استخدام مَعلم في سياق وجهة معيّنة
إذا كان العنوان يتضمّن العلامتَين ADDRESS وARRIVAL، يعني ذلك أنّ المَعلم بارز محليًا وقريب من الوجهة.
| عمليات التعداد | |
|---|---|
TAG_UNSPECIFIED |
لم يتم الاستخدام. |
ADDRESS |
مكان بارز محليًا يمكن استخدامه لتحديد الموقع الجغرافي العام للوجهة عادةً ما تكون على بُعد بضع مئات من الأمتار من الوجهة. وهي تشبه المعالم التي تعرضها ميزة "أوصاف العناوين" في Geocoding API: https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors. |
ARRIVAL |
مكان يمكن استخدامه للمساعدة في الوصول إلى الوجهة تكون مفيدة للتنقّل عندما تكون قريبًا من الوجهة. على سبيل المثال، قد يكون هذا المعلم مكانًا يقع على الجانب الآخر من الشارع مقابل الوجهة. عادةً ما يكون المعلم الذي يحمل هذه العلامة أقرب إلى الوجهة من المعالم التي تحمل العلامة ADDRESS. |
المدخل
المدخل هو زوج إحداثيات واحد لخط العرض/خط الطول يحدّد الموقع الجغرافي لنقطة دخول وخروج لمكان معيّن.
| تمثيل JSON |
|---|
{ "location": { object ( |
| الحقول | |
|---|---|
location |
تمثّل هذه السمة موقع المدخل. |
tags[] |
قائمة بالعلامات التي تصف المدخل |
place |
تمثّل هذه السمة البنية التي يقع عليها المدخل فعليًا، وذلك بالتنسيق |
streetViewThumbnail |
صورة مصغّرة من "التجوّل الافتراضي" تُظهر المدخل يمكن طلب الصورة من Street View Static API. يُرجى الاطّلاع على https://developers.google.com/maps/documentation/streetview/request-streetview. |
streetViewAnnotation |
تعليق توضيحي حول المدخل الذي تم عرضه في |
Entrance.Tag
الخصائص التي تصف المدخل
| عمليات التعداد | |
|---|---|
TAG_UNSPECIFIED |
لم يتم الاستخدام. |
PREFERRED |
من المحتمل أن يتيح المدخل الوصول الفعلي إلى المكان الأساسي في الوجهة التي تم عرضها. يمكن أن يكون للمكان عدة مداخل مفضّلة. إذا لم يكن للمدخل هذه العلامة، يعني ذلك أنّ المدخل يقع فعليًا في المبنى نفسه الذي يقع فيه المكان الأساسي، ولكنّه لا يتيح بالضرورة الوصول إلى المكان. على سبيل المثال، إذا كان المكان الأساسي هو مطعم في مركز تجاري على شكل شريط، ستكون المداخل "المفضّلة" هي تلك التي من المحتمل أن تؤدي إلى المطعم نفسه، بينما ستكون المداخل الأخرى التي تم عرضها هي مداخل أخرى للمبنى، مثل المداخل إلى مطاعم أخرى في المركز التجاري على شكل شريط. إذا كان المكان الأساسي هو مبنى، ستكون مداخل ملاحظة: قد لا يوفّر مدخل |
StreetViewThumbnail
تمثّل هذه السمة مَعلمات لعرض صورة مصغّرة من "التجوّل الافتراضي" من Google. يمكن استخدام هذه المَعلمات لطلب صورة "تجوّل افتراضي" من Street View Static API. يُرجى الاطّلاع على https://developers.google.com/maps/documentation/streetview/request-streetview.
| تمثيل JSON |
|---|
{ "pano": string, "widthPx": integer, "heightPx": integer, "headingDegree": number, "pitchDegree": number, "fovDegree": number } |
| الحقول | |
|---|---|
pano |
معرّف بانوراما محدّد |
widthPx |
عرض الصورة المصغّرة الناتجة بالبكسل ملاحظة: عند طلب التعليقات التوضيحية إلى جانب الصورة المصغّرة، يجب استخدام قيم الارتفاع والعرض هذه في طلب بيانات من واجهة برمجة التطبيقات للتجوّل الافتراضي لضمان توافق إحداثيات التعليقات التوضيحية بشكل صحيح مع الصورة. |
heightPx |
ارتفاع الصورة المصغّرة الناتجة بالبكسل ملاحظة: عند طلب التعليقات التوضيحية مع الصورة المصغّرة، يجب استخدام قيم الارتفاع والعرض هذه في طلب بيانات من واجهة برمجة التطبيقات Street View API لضمان محاذاة إحداثيات التعليقات التوضيحية بشكل صحيح مع الصورة. |
headingDegree |
الاتجاه الأفقي للكاميرا بالدرجات النطاق [0, 360). يشير الرقم 0 إلى الشمال والرقم 90 إلى الشرق. |
pitchDegree |
الاتجاه العمودي للكاميرا بالدرجات النطاق [-90, 90]. 0 هو الأفق، و+90 هو للأعلى مباشرةً، و-90 هو للأسفل مباشرةً. |
fovDegree |
مجال الرؤية الأفقي بالدرجات النطاق (0, 180]. يتحكّم في مستوى التكبير أو التصغير. ويعني مجال الرؤية الأصغر تكبيرًا أكبر. |
ImageAnnotation
تعليق توضيحي على صورة مصغّرة، مثل مضلّع يحدّد مدخلاً
| تمثيل JSON |
|---|
{
"coordinates": [
{
object ( |
| الحقول | |
|---|---|
coordinates[] |
قائمة بالإحداثيات التي تشكّل مضلّعًا في الصورة يتم ترتيب الإحداثيات عكس عقارب الساعة. |
ImageAnnotation.Coordinate
إحداثيات البكسل لنقطة على الصورة نقطة الأصل (0,0) هي الزاوية العلوية اليمنى من البكسل العلوي الأيمن للصورة، مع محور س يشير إلى اليمين ومحور ص يشير إلى الأسفل.
| تمثيل JSON |
|---|
{ "xPx": number, "yPx": number } |
| الحقول | |
|---|---|
xPx |
الإحداثي X |
yPx |
الإحداثي Y |
Destination.ParkingOptions
معلومات عن خيارات ركن السيارة في الوجهة
| تمثيل JSON |
|---|
{
"availability": enum ( |
| الحقول | |
|---|---|
availability |
توضّح هذه السمة مدى توفّر مواقف للسيارات في هذه الوجهة. |
onsiteParking |
تتوفر مواقف للسيارات في موقع الوجهة. |
freeParkingLot |
يوفر مواقف مجانية للسيارات. |
paidParkingLot |
يوفّر مواقف سيارات برسوم |
freeStreetParking |
يوفّر موقف سيارات مجانيًا في الشارع |
paidStreetParking |
يوفّر موقف سيارات في الشارع برسوم |
valetParking |
يوفّر المكان خدمة صفّ السيارات. |
freeGarageParking |
يوفّر المكان موقف سيارات مجانيًا. |
paidGarageParking |
يوفّر المكان موقف سيارات برسوم. |
Destination.ParkingOptions.Availability
مقياس مجمّع لمدى صعوبة العثور على موقف سيارات عند زيارة هذا المكان
قد تتم إضافة قيم جديدة في المستقبل.
| عمليات التعداد | |
|---|---|
AVAILABILITY_UNSPECIFIED |
لا تتوفّر معلومات عن مدى توفّر مواقف للسيارات. |
PLENTY |
يتوفّر الكثير من مواقف السيارات. |
SOMEWHAT_DIFFICULT |
من الصعب نوعًا ما العثور على موقف سيارات. |
DIFFICULT |
من الصعب جدًا العثور على موقف سيارات. |
Destination.ArrivalSummary
ملخّص من إنشاء الذكاء الاصطناعي حول تجربة الوصول إلى الوجهة
| تمثيل JSON |
|---|
{ "text": { object ( |
| الحقول | |
|---|---|
text |
تعرض هذه السمة ملخّصًا لتجربة الوصول إلى الوجهة. |
flagContentUrl |
رابط يمكن للمستخدمين من خلاله الإبلاغ عن مشكلة في الملخّص. |
disclosureText |
للعرض فقط. يحتوي على نص الإفصاح لملخّص الوصول. |