Method: geocode.destinations.searchDestinations

تُجري هذه الطريقة عملية بحث عن الوجهات وتعرض قائمة بالوجهات.

طلب HTTP

POST https://geocode.googleapis.com/v4/geocode/destinations

يستخدِم عنوان URL بنية تحويل الترميز إلى gRPC.

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

تمثيل JSON 
{
  "travelModes": [
    enum (NavigationPoint.TravelMode)
  ],
  "languageCode": string,
  "regionCode": string,

  // Union field primary_query can be only one of the following:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of list of possible types for union field primary_query.
}
الحقول
travelModes[]

enum (NavigationPoint.TravelMode)

اختيارية: تمثّل هذه السمة وسائل النقل التي سيتم فلترة نقاط التنقّل وفقًا لها. يؤثر ذلك في حقل navigationPoints الذي يتم عرضه في الردّ. وفي حال تركها فارغة، يتم عرض نقاط التنقّل لجميع وسائل النقل.
languageCode

string

اختيارية: اللغة التي يجب عرض النتائج بها
regionCode

string

اختيارية: رمز المنطقة رمز المنطقة، ويتم تحديده كقيمة من حرفَين لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD). تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري. تؤثّر هذه المَعلمة أيضًا في النتائج الواردة من الخدمة، ولكنّها لا تقيّدها بالكامل.

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

يتم إنشاء الوجهات حول طلب البحث الأساسي المحدّد.

ملاحظة: لا تتوفّر هذه الميزة إلا للأماكن والعناوين التي يمكن أن تكون وجهة للملاحة. على سبيل المثال، يمكن استخدام مكان يمثّل منزلاً أو مجمّعًا سكنيًا كطلب البحث الأساسي، ولكن لا يمكن استخدام الأماكن التي تمثّل منطقة محلية أو منطقة إدارية كطلب البحث الأساسي. يمكن أن يكون التعليق primary_query إحدى القيم التالية فقط:
place

string

اسم المورد الخاص بمكان معيّن، بتنسيق places/{placeId}.
addressQuery

object (SearchDestinationsRequest.AddressQuery)

تمثّل هذه السمة عنوان الشارع.
locationQuery

object (SearchDestinationsRequest.LocationQuery)

موقع جغرافي دقيق

نص الاستجابة

رسالة الردّ على DestinationService.SearchDestinations

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ]
}
الحقول
destinations[]

object (Destination)

قائمة بالوجهات

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

نطاقات الأذونات

يجب توفير أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/maps-platform.geocode
  • https://www.googleapis.com/auth/maps-platform.destinations

SearchDestinationsRequest.AddressQuery

تمثّل هذه السمة عنوان الشارع الذي تريد البحث عنه. يجب تحديد العناوين وفقًا للتنسيق الذي تستخدمه خدمة البريد الوطنية في البلد المعني.

تمثيل JSON 
{

  // Union field kind can be only one of the following:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of list of possible types for union field kind.
}
الحقول
حقل الربط kind طلب البحث عن العنوان يمكن أن يكون التعليق kind إحدى القيم التالية فقط:
address

object (PostalAddress)

عنوان شارع بتنسيق عنوان بريدي
addressQuery

string

عنوان شارع منسَّق كسطر واحد

SearchDestinationsRequest.LocationQuery

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

ملاحظة: إذا كان طلب البحث عن الموقع الجغرافي داخل مبنى يحتوي على مبانٍ فرعية، من الممكن أن يكون المكان الأساسي الذي يتم عرضه هو مبنى فرعي. وفي هذه الحالات، سيتضمّن الحقل containingPlaces المبنى.

تمثيل JSON 
{
  "placeFilter": {
    object (SearchDestinationsRequest.LocationQuery.PlaceFilter)
  },

  // Union field kind can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field kind.
}
الحقول
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

اختيارية: الفلاتر التي سيتم تطبيقها على المرشحين للوجهة
حقل الربط kind تمثّل هذه السمة طلب البحث عن الموقع الجغرافي. يمكن أن يكون التعليق kind إحدى القيم التالية فقط:
location

object (LatLng)

موقع جغرافي دقيق يمثّل خطوط الطول والعرض

SearchDestinationsRequest.LocationQuery.PlaceFilter

الفلاتر التي سيتم تطبيقها على الوجهات المرشحة

تمثيل JSON 
{
  "structureType": enum (PlaceView.StructureType),
  "addressability": enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)
}
الحقول
structureType

enum (PlaceView.StructureType)

اختيارية: في حال تحديد هذه السمة، نضمن أن تتضمّن جميع الوجهات مكانًا أساسيًا من نوع البنية هذا. قد يؤدي ذلك إلى فلترة بعض الوجهات أو تقليل دقة الوجهات المعروضة أو تحسينها.

على سبيل المثال، إذا تم تحديد GROUNDS، ستتضمّن جميع الوجهات التي يتم عرضها مكانًا أساسيًا بنوع البنية GROUNDS. يمكن أن يؤدي ذلك إلى فلترة بعض الوجهات التي لا تشكّل جزءًا من الأراضي، أو إلى تقليل دقة الوجهات التي يتم عرضها إلى مستوى الأراضي.

ومن الاستخدامات الأخرى لهذا الحقل استخراج مضلّعات عرض المباني بسهولة أكبر. على سبيل المثال، إذا تم تحديد BUILDING، سيكون المضلّع المعروض للمكان الأساسي هو المبنى في الموقع الجغرافي المحدّد.
addressability

enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)

اختيارية: في حال تحديد هذه السمة، يتم عرض الوجهات التي تستوفي معايير إمكانية الاستهداف المقابلة فقط.

PlaceView.StructureType

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

عمليات التعداد
STRUCTURE_TYPE_UNSPECIFIED لم يتم الاستخدام.
POINT موقع جغرافي على شكل نقطة
SECTION قسم فرعي من مبنى
BUILDING مبنى
GROUNDS مساحة كبيرة تحتوي عادةً على مبانٍ متعددة، مثل حرم جامعي أو مجمّع سكني أو مركز تسوّق

SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability

تحدّد هذه السمة خيارات فلترة مدى توفّر الإعلانات. قد تتم إضافة قيم جديدة في المستقبل.

عمليات التعداد
ADDRESSABILITY_UNSPECIFIED في حال عدم تحديدها، ستختار الخدمة قيمة تلقائية مناسبة.
ANY لا تُعدّ إمكانية الاستهداف معيارًا للفلترة. يتم عرض الوجهات بغض النظر عن إمكانية استهدافها.
PRIMARY ستتضمّن جميع الوجهات التي يتم عرضها مكانًا أساسيًا يتضمّن عنوانًا أو اسمًا على مستوى الشارع.
WEAK ستتضمّن جميع الوجهات التي يتم عرضها إما مكانًا رئيسيًا أو وجهة فرعية مع عنوان أو اسم على مستوى الشارع.

الوجهة

وجهة ويشمل ذلك المكان الأساسي والأماكن ذات الصلة والمداخل ونقاط التنقّل.

تمثيل JSON 
{
  "primary": {
    object (PlaceView)
  },
  "containingPlaces": [
    {
      object (PlaceView)
    }
  ],
  "subDestinations": [
    {
      object (PlaceView)
    }
  ],
  "landmarks": [
    {
      object (Landmark)
    }
  ],
  "entrances": [
    {
      object (Entrance)
    }
  ],
  "navigationPoints": [
    {
      object (NavigationPoint)
    }
  ]
}
الحقول
primary

object (PlaceView)

المكان الأساسي الذي يحدّده primary_query في الطلب
containingPlaces[]

object (PlaceView)

الأماكن الأقل دقة التي يتضمّنها المكان الأساسي على سبيل المثال، المجمّع السكني الذي يضم هذا المبنى.
subDestinations[]

object (PlaceView)

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

ملاحظة: مقارنةً بالوجهة الفرعية SubDestination التي تعرضها واجهة برمجة التطبيقات Places API، تكون قائمة الوجهات الفرعية هذه أكثر شمولاً، وتحتوي كل وجهة فرعية على مزيد من المعلومات.
landmarks[]

object (Landmark)

المعالم التي يمكن استخدامها للإشارة إلى مكان الوجهة أو المساعدة في الوصول إليها
entrances[]

object (Entrance)

مداخل هذه الوجهة
navigationPoints[]

object (NavigationPoint)

نقاط التنقّل لهذه الوجهة

PlaceView

تمثّل هذه السمة طريقة عرض مكان في Places API. وتوفّر أيضًا معلومات إضافية خاصة بالوجهات، مثل نوع البنية والمضلّع المعروض.

في بعض الحالات، قد يختلف PlaceView الذي يحمل رقم تعريف المكان نفسه عمّا تعرضه Places API للحقلَين types وdisplayName.

تمثيل JSON 
{
  "place": string,
  "placeId": string,
  "displayName": {
    object (LocalizedText)
  },
  "primaryType": string,
  "types": [
    string
  ],
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "structureType": enum (PlaceView.StructureType),
  "location": {
    object (LatLng)
  },
  "displayPolygon": {
    object
  },
  "addressComponents": [
    {
      object (PlaceView.AddressComponent)
    }
  ]
}
الحقول
place

string

اسم المورد الخاص بهذا المكان، بالتنسيق places/{placeId} يمكن استخدامها للبحث عن المكان.
placeId

string

المعرّف الفريد لمكان معيّن
displayName

object (LocalizedText)

وصف المكان الذي يمكن لشخص عادي قراءته على سبيل المثال، "البوابة ب" أو "ماكدونالدز"
primaryType

string

تمثّل هذه السمة نوع المكان الأساسي. راجِع https://developers.google.com/maps/documentation/places/web-service/place-types للاطّلاع على قائمة بالقيم المحتملة.

ملاحظة: لا تتم تعبئة هذا الحقل دائمًا. يجب أن تكون مستعدًا لاستخدام الحقل types في مثل هذه الحالات.
types[]

string

جميع أنواع الأماكن المرتبطة بهذا المكان راجِع https://developers.google.com/maps/documentation/places/web-service/place-types للاطّلاع على قائمة بالقيم المحتملة.
formattedAddress

string

عنوان من سطر واحد
postalAddress

object (PostalAddress)

العنوان المنظَّم
structureType

enum (PlaceView.StructureType)

نوع البنية المقابلة لهذا المكان
location

object (LatLng)

الموقع الجغرافي لهذا المكان بالنسبة إلى الأماكن التي تتضمّن مضلّعات عرض، يمكن أن يمثّل ذلك موضعًا جيدًا لوضع علامة على الخريطة.
displayPolygon

object (Struct format)

مخطط مضلّع للمكان بتنسيق GeoJSON، باستخدام تنسيق RFC 7946: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6

ملاحظة: يتيح تنسيق RFC 7946 استخدام MultiPolygons، لذا يمكن أن يمثّل عنصر displayPolygon واحد مضلّعات متعدّدة.
addressComponents[]

object (PlaceView.AddressComponent)

مكوّنات متكرّرة لكل مستوى منطقة

PlaceView.AddressComponent

المكوّنات المنظَّمة التي تشكّل العنوان المنسَّق، إذا كانت هذه المعلومات متاحة

تمثيل JSON 
{
  "longText": string,
  "shortText": string,
  "types": [
    string
  ],
  "languageCode": string
}
الحقول
longText

string

تمثّل هذه السمة الوصف النصي الكامل أو اسم مكوّن العنوان. على سبيل المثال، قد يتضمّن أحد مكوّنات العنوان الخاص ببلد أستراليا اسمًا طويلاً هو "أستراليا".
shortText

string

اسم نصي مختصر لمكوّن العنوان، إذا كان متاحًا. على سبيل المثال، قد يكون الاسم المختصر لمكوّن العنوان الخاص ببلد أستراليا هو "AU".
types[]

string

مصفوفة تشير إلى أنواع مكوّنات العنوان.

لمزيد من التفاصيل، يُرجى الاطّلاع على https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types.
languageCode

string

تمثّل هذه السمة اللغة المستخدَمة لتنسيق هذا المكوّن، وذلك بتنسيق CLDR.

مَعلم

تُستخدَم المعالم للإشارة إلى مكان الوجهة أو المساعدة في الوصول إليها.

تمثيل JSON 
{
  "relationalDescription": {
    object (LocalizedText)
  },
  "tags": [
    enum (Landmark.Tag)
  ],
  "straightLineDistanceMeters": number,
  "travelDistanceMeters": number,

  // Union field landmark can be only one of the following:
  "place": {
    object (PlaceView)
  }
  // End of list of possible types for union field landmark.
}
الحقول
relationalDescription

object (LocalizedText)

وصف يمكن لشخص عادي قراءته لكيفية ارتباط الوجهة بالمعلم على سبيل المثال: "بالقرب من مبنى إمباير ستيت" أو "مقابل البيت الأبيض".
tags[]

enum (Landmark.Tag)

علامات تصف كيفية استخدام المعلم في سياق الوجهة.
straightLineDistanceMeters

number

النتائج فقط. المسافة المستقيمة من هذا المعلم إلى الوجهة بالأمتار
travelDistanceMeters

number

للعرض فقط. المسافة سيرًا على الأقدام من هذا المعلم إلى الوجهة بالأمتار
حقل الربط landmark تمثّل هذه السمة المَعلم. يمكن أن يكون التعليق landmark إحدى القيم التالية فقط:
place

object (PlaceView)

المكان الذي يمثّل هذا المعلم

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 (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string
}
الحقول
location

object (LatLng)

موقع المدخل
tags[]

enum (Entrance.Tag)

قائمة بالعلامات التي تصف المدخل
place

string

تمثّل هذه السمة البنية التي يقع عليها المدخل فعليًا، وذلك بالتنسيق places/{placeId}.

Entrance.Tag

الخصائص التي تصف المدخل

عمليات التعداد
TAG_UNSPECIFIED غير مستخدَم
PREFERRED

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

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

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

ملاحظة: قد لا يوفّر مدخل PREFERRED إمكانية الوصول إلى المكان الأساسي، وقد يوفّر مدخل غير تابع لـ PREFERRED إمكانية الوصول إلى المكان الأساسي.