Method: geocode.destinations.searchDestinations

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

طلب HTTP

POST https://geocode.googleapis.com/v4alpha/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 استعلم عن الوجهة الأساسية. يمكن أن يكون هذا مكانًا أو عنوانًا محدّدًا بالكامل أو موقعًا جغرافيًا LatLng. لن يكون من الممكن تحويل بعض الأماكن والعناوين التي تتضمّن الحد الأدنى من المعلومات إلى وجهة.

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

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

موقع جغرافي دقيق بتنسيق 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)
    }
  ],
  "parkingOptions": {
    object (Destination.ParkingOptions)
  },
  "arrivalSummary": {
    object (Destination.ArrivalSummary)
  }
}
الحقول
primary

object (PlaceView)

المكان الأساسي الذي تم تحديده بواسطة primary_query في الطلب.
containingPlaces[]

object (PlaceView)

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

object (PlaceView)

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

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

object (Landmark)

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

object (Entrance)

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

object (NavigationPoint)

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

object (Destination.ParkingOptions)

خيارات مواقف السيارات في هذه الوجهة
arrivalSummary

object (Destination.ArrivalSummary)

ملخّص من إنشاء الذكاء الاصطناعي حول تجربة الوصول إلى الوجهة

PlaceView

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

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

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

string

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

string

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

object (LocalizedText)

وصف المكان يمكن لشخص عادي قراءته على سبيل المثال، "البوابة B" أو "ماكدونالدز"
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 واحد مضلّعات متعدّدة.

مَعلم

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

تمثيل 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,
  "streetViewThumbnail": {
    object (StreetViewThumbnail)
  },
  "streetViewAnnotation": {
    object (ImageAnnotation)
  }
}
الحقول
location

object (LatLng)

تمثّل هذه السمة الموقع الجغرافي للمدخل.
tags[]

enum (Entrance.Tag)

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

string

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

object (StreetViewThumbnail)

صورة مصغّرة لـ "التجوّل الافتراضي" تعرض المدخل يمكن طلب الصورة من Street View Static API. يُرجى الاطّلاع على https://developers.google.com/maps/documentation/streetview/request-streetview.
streetViewAnnotation

object (ImageAnnotation)

تعليق توضيحي على المدخل الذي تم عرضه في streetViewThumbnail أعلاه

Entrance.Tag

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

عمليات التعداد
TAG_UNSPECIFIED لم يتم استخدامه.
PREFERRED

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

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

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

ملاحظة: قد لا يتيح المدخل PREFERRED الوصول إلى المكان الأساسي، وقد يتيح المدخل غير 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

string

معرّف بانوراما محدّد
widthPx

integer

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

integer

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

number

الاتجاه الأفقي للكاميرا بالدرجات النطاق [0, 360). يشير الرقم 0 إلى الشمال والرقم 90 إلى الشرق.
pitchDegree

number

تمثّل هذه السمة اتجاه الكاميرا العمودي بالدرجات. النطاق [-90, 90]. 0 هو الأفق، و+90 هو للأعلى مباشرةً، و-90 هو للأسفل مباشرةً.
fovDegree

number

مجال الرؤية الأفقي بالدرجات النطاق (0, 180]. يتحكّم في مستوى التكبير أو التصغير. كلما كان مجال الرؤية أصغر، زاد التكبير.

ImageAnnotation

تعليق توضيحي على صورة مصغّرة، مثل مضلّع يحدّد مدخلاً

تمثيل JSON 
{
  "coordinates": [
    {
      object (ImageAnnotation.Coordinate)
    }
  ]
}
الحقول
coordinates[]

object (ImageAnnotation.Coordinate)

قائمة بالإحداثيات التي تشكّل مضلّعًا في الصورة يتم ترتيب الإحداثيات عكس اتجاه عقارب الساعة.

ImageAnnotation.Coordinate

إحداثي البكسل لنقطة في الصورة نقطة الأصل (0,0) هي الزاوية العلوية اليمنى من البكسل العلوي الأيسر للصورة، مع توجيه المحور x إلى اليمين والمحور y إلى الأسفل.

تمثيل JSON 
{
  "xPx": number,
  "yPx": number
}
الحقول
xPx

number

الإحداثي X
yPx

number

الإحداثي Y

Destination.ParkingOptions

معلومات عن خيارات ركن السيارة في الوجهة

تمثيل JSON 
{
  "availability": enum (Destination.ParkingOptions.Availability),
  "onsiteParking": boolean,
  "freeParkingLot": boolean,
  "paidParkingLot": boolean,
  "freeStreetParking": boolean,
  "paidStreetParking": boolean,
  "valetParking": boolean,
  "freeGarageParking": boolean,
  "paidGarageParking": boolean
}
الحقول
availability

enum (Destination.ParkingOptions.Availability)

تعرض هذه السمة معلومات توفّر مواقف السيارات في هذه الوجهة.
onsiteParking

boolean

تتوفر مواقف للسيارات في موقع الوجهة.
freeParkingLot

boolean

يوفر مواقف مجانية للسيارات.
paidParkingLot

boolean

يوفّر مواقف سيارات برسوم
freeStreetParking

boolean

يوفّر موقف سيارات مجانيًا في الشارع
paidStreetParking

boolean

يوفّر موقف سيارات في الشارع برسوم
valetParking

boolean

يوفّر خدمة صفّ السيارات.
freeGarageParking

boolean

يوفّر موقف سيارات مجانيًا.
paidGarageParking

boolean

يوفّر موقف سيارات مدفوع في مرآب

Destination.ParkingOptions.Availability

مقياس مجمّع لمدى صعوبة العثور على موقف سيارات عند زيارة هذا المكان

قد تتم إضافة قيم جديدة في المستقبل.

عمليات التعداد
AVAILABILITY_UNSPECIFIED لا تتوفّر معلومات حول إمكانية توفّر مواقف للسيارات.
PLENTY تتوفّر مواقف سيارات كافية.
SOMEWHAT_DIFFICULT من الصعب نوعًا ما العثور على موقف سيارات.
DIFFICULT من الصعب جدًا العثور على موقف سيارات.

Destination.ArrivalSummary

ملخّص من إنشاء الذكاء الاصطناعي حول تجربة الوصول إلى الوجهة

تمثيل JSON 
{
  "text": {
    object (LocalizedText)
  },
  "flagContentUrl": string,
  "disclosureText": {
    object (LocalizedText)
  }
}
الحقول
text

object (LocalizedText)

ملخّص لتجربة الوصول إلى الوجهة
flagContentUrl

string

رابط يمكن للمستخدمين من خلاله الإبلاغ عن مشكلة في الملخّص
disclosureText

object (LocalizedText)

النتائج فقط. تحتوي هذه السمة على نص الإفصاح الخاص بملخّص الوصول.