- طلب HTTP
- نص الطلب
- نص الاستجابة
- RankPreference
- LocationBias
- LocationRestriction
- EVOptions
- SearchAlongRouteParameters
- الخط المتعدّد
- ContextualContent
- السبب
- ReviewJustification
- HighlightedText
- HighlightedTextRange
- BusinessAvailabilityAttributesJustification
البحث عن الأماكن استنادًا إلى طلب بحث نصي
طلب HTTP
POST https://places.googleapis.com/v1/places:searchText
يستخدِم عنوان URL بنية تحويل ترميز gRPC.
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "textQuery": string, "languageCode": string, "regionCode": string, "rankPreference": enum ( |
الحقول | |
---|---|
text |
مطلوب. طلب البحث النصي للبحث النصي |
language |
سيتم عرض تفاصيل المكان باللغة المفضّلة في حال توفّرها. إذا لم يتم تحديد رمز اللغة أو لم يتم التعرّف عليه، قد يتم عرض تفاصيل المكان بأي لغة، مع تفضيل اللغة الإنجليزية إذا كانت هذه التفاصيل متوفّرة. القائمة الحالية للّغات المتاحة: https://developers.google.com/maps/faq#languagesupport. |
region |
رمز البلد أو المنطقة بترميز Unicode (CLDR) للموقع الجغرافي الذي يتم إرسال الطلب منه تُستخدَم هذه المَعلمة لعرض تفاصيل المكان، مثل اسم المكان الخاص بالمنطقة، إن توفّر. يمكن أن تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري. لمزيد من المعلومات، يُرجى الاطّلاع على https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html. يُرجى العِلم أنّ رموز المناطق المكونة من 3 أرقام غير متاحة حاليًا. |
rank |
كيفية ترتيب النتائج في الردّ |
included |
نوع المكان المطلوب القائمة الكاملة للأنواع المتوافقة: https://developers.google.com/maps/documentation/places/web-service/place-types. لا تتيح سوى نوع واحد مضمّن. |
open |
تُستخدَم لتقييد البحث على الأماكن المفتوحة حاليًا. القيمة التلقائية هي false. |
min |
فلترة النتائج التي يكون متوسّط تقييم المستخدمين لها أقل من هذا الحدّ بدقة يجب أن تكون القيمة الصالحة عددًا عشريًا يتراوح بين 0 و5 (بما في ذلك) بمعدّل تكرار 0.5، أي [0, 0.5, 1.0, ... , 5.0] بشكل شامل. سيتم تقريب التقييم المُدخل إلى أقرب 0.5(الحدّ الأقصى). على سبيل المثال، سيؤدي التقييم 0.6 إلى استبعاد جميع النتائج التي تقلّ تقييماتها عن 1.0. |
maxResultCount |
تم إيقاف هذه السياسة نهائيًا، لذا يُرجى استخدام الحد الأقصى لعدد النتائج التي يمكن عرضها في كل صفحة إذا كان عدد النتائج المتاحة أكبر من إذا تم تحديد كل من |
page |
اختيارية: الحد الأقصى لعدد النتائج التي يمكن عرضها في كل صفحة إذا كان عدد النتائج المتاحة أكبر من إذا تم تحديد كل من |
page |
اختيارية: رمز مميّز للصفحة، تمّ تلقّيه من مكالمة TextSearch سابقة قدِّم هذا المرجع لاسترداد الصفحة اللاحقة. عند تقسيم الصفحات، يجب أن تتطابق جميع المَعلمات التي يتم تقديمها إلى TextSearch، باستثناء |
price |
تُستخدَم لتقييد البحث على الأماكن التي تم وضع علامة عليها كمستويات أسعار معيّنة. يمكن للمستخدمين اختيار أي مجموعات من مستويات الأسعار. الإعداد التلقائي لاختيار جميع مستويات الأسعار |
strict |
تُستخدَم لضبط فلترة صارمة للنوع في includedType. في حال ضبطها على "صحيح"، سيتم عرض النتائج من النوع نفسه فقط. القيمة التلقائية هي false. |
location |
المنطقة التي تريد البحث فيها. يُعدّ هذا الموقع الجغرافي عاملاً مؤثرًا، ما يعني أنّه قد يتم عرض نتائج حول الموقع الجغرافي المحدّد. لا يمكن ضبطه مع locationRestriction. |
location |
المنطقة التي تريد البحث فيها. يُعدّ هذا الموقع الجغرافي بمثابة قيد، ما يعني أنّه لن يتم عرض نتائج خارج الموقع الجغرافي المحدّد. لا يمكن ضبطه مع locationBias. |
ev |
اختيارية: يمكنك ضبط خيارات المركبات الكهربائية القابلة للبحث في طلب البحث عن مكان. |
routing |
اختيارية: مَعلمات إضافية لتوجيه البيانات إلى النتائج |
search |
اختيارية: نموذج للمَعلمات الإضافية للبحث على طول مسار |
include |
اختيارية: تضمين الأنشطة التجارية التي تعمل في منطقة خدمة فقط إذا تم ضبط الحقل على true النشاط التجاري لمنطقة الخدمة هو نشاط تجاري يزور العملاء أو يقدّم خدماته لهم مباشرةً، ولكنّه لا يوفّر الخدمة في موقعه الجغرافي. على سبيل المثال، خدمات التنظيف أو السباكة لا تتوفّر لهذه الأنشطة التجارية عناوين جغرافية أو مواقع جغرافية على "خرائط Google". لن تعرض ميزة "الأماكن" حقولًا تشمل |
نص الاستجابة
نموذج استجابة لـ places.searchText
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "places": [ { object ( |
الحقول | |
---|---|
places[] |
قائمة بالأماكن التي تستوفي معايير البحث النصي التي حدّدها المستخدم |
routing |
قائمة بملخصات التوجيه التي يرتبط فيها كل إدخال بالمكان المقابل له في الفهرس نفسه في حقل |
contextual |
ميزة تجريبية: يُرجى الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative للحصول على مزيد من التفاصيل. قائمة بالمحتوى السياقي الذي يرتبط كل إدخال فيه بالموقع المقابل له في الفهرس نفسه في حقل places يُفضّل استخدام المحتوى ذي الصلة بالموضوع |
next |
رمز مميّز يمكن إرساله على شكل |
search |
يسمح الرابط للمستخدم بالبحث باستخدام طلب البحث النصي نفسه المحدّد في الطلب على "خرائط Google". |
RankPreference
كيفية ترتيب النتائج في الردّ
عمليات التعداد | |
---|---|
RANK_PREFERENCE_UNSPECIFIED |
بالنسبة إلى طلب بحث فئوي، مثل "مطاعم في مدينة نيويورك"، يكون عامل الترتيب التلقائي هو "الصلة". بالنسبة إلى طلبات البحث غير الفئوية، مثل "ماونتن فيو، كاليفورنيا"، ننصحك بعدم ضبط rankPreference. |
DISTANCE |
ترتيب النتائج حسب المسافة |
RELEVANCE |
ترتيب النتائج حسب مدى صلتها بموضوع البحث يتم تحديد ترتيب الترتيب حسب تسلسل الترتيب العادي. |
LocationBias
المنطقة التي تريد البحث فيها. يُعدّ هذا الموقع الجغرافي عاملاً مؤثرًا، ما يعني أنّه قد يتم عرض نتائج حول الموقع الجغرافي المحدّد.
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الربط يمكن أن يكون |
|
rectangle |
مربّع مستطيل محدّد من خلال الزاوية الشمالية الشرقية والجنوبية الغربية يجب أن تكون |
circle |
دائرة محدّدة بنقطة المركز ونصف القطر |
LocationRestriction
المنطقة التي تريد البحث فيها. يُعدّ هذا الموقع الجغرافي بمثابة قيد، ما يعني أنّه لن يتم عرض نتائج خارج الموقع الجغرافي المحدّد.
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الربط يمكن أن يكون |
|
rectangle |
مربّع مستطيل محدّد من خلال الزاوية الشمالية الشرقية والجنوبية الغربية يجب أن تكون |
EVOptions
خيارات المركبات الكهربائية القابلة للبحث في طلب البحث عن مكان
تمثيل JSON |
---|
{
"minimumChargingRateKw": number,
"connectorTypes": [
enum ( |
الحقول | |
---|---|
minimum |
اختيارية: الحد الأدنى لمعدل الشحن المطلوب بالكيلوواط يتم استبعاد مكان يقلّ فيه سعر الشحن عن السعر المحدّد. |
connector |
اختيارية: قائمة أنواع وصلات المركبات الكهربائية المفضّلة تتم فلترة مكان لا يتيح استخدام أيّ من أنواع الموصّلات المدرَجة. |
SearchAlongRouteParameters
تحدِّد هذه السمة خطًا متعدّد الأضلاع تم احتسابه مسبقًا من Routes API لتحديد المسار المطلوب البحث عنه. يشبه البحث على طول مسار استخدام خيار الطلب locationBias
أو locationRestriction
لتوجيه نتائج البحث. ومع ذلك، في حين أنّ خيارَي locationBias
وlocationRestriction
يسمحان لك بتحديد منطقة لتوجيه نتائج البحث، يتيح لك هذا الخيار توجيه النتائج على طول مسار رحلة.
لا يمكن ضمان أن تكون النتائج على طول المسار المقدَّم، بل يتم ترتيبها ضمن منطقة البحث المحدَّدة بالخط المتعدّد، واختياريًا حسب locationBias
أو locationRestriction
استنادًا إلى الحد الأدنى لمُدد الالتفاف من نقطة المغادرة إلى الوجهة. قد تكون النتائج على طول مسار بديل، خاصةً إذا لم يحدِّد الخط المتعدّد الأضلاع المقدَّم مسارًا مثاليًا من نقطة الانطلاق إلى الوجهة.
تمثيل JSON |
---|
{
"polyline": {
object ( |
الحقول | |
---|---|
polyline |
مطلوب. خطوط المسار المتعددة |
خط متعدد
خطوط متعددة لمسار تتيح هذه السمة استخدام خطوط متعددة مُشفَّرة فقط، والتي يمكن تمريرها كسلسلة وتتضمّن ضغطًا بأقل قدر من الخسارة. هذا هو الإخراج التلقائي لواجهة برمجة التطبيقات Routes API.
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الربط polyline_type تُحاط بنوع الخطوط المتعددة. القيمة التلقائية لمخرجات Routes API هي encoded_polyline . يمكن أن يكون polyline_type واحدًا فقط مما يلي: |
|
encoded |
خط متعدد الأضلاع مشفَّر، كما تعرضه Routes API تلقائيًا اطّلِع على أدوات التشفير وفك التشفير. |
ContextualContent
ميزة تجريبية: يُرجى الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative للحصول على مزيد من التفاصيل.
المحتوى الذي يكون سياقيًا لطلب البحث عن مكان
تمثيل JSON |
---|
{ "reviews": [ { object ( |
الحقول | |
---|---|
reviews[] |
قائمة بالمراجعات حول هذا المكان، ذات صلة بطلب البحث عن المكان |
photos[] |
معلومات (بما في ذلك الإحالات) عن صور هذا المكان، ذات صلة بطلب البحث عن المكان |
justifications[] |
ميزة تجريبية: يُرجى الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative للحصول على مزيد من التفاصيل. الأسباب التي تجعل المكان ملائمًا |
السبب
ميزة تجريبية: يُرجى الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative للحصول على مزيد من التفاصيل.
الأسباب التي تجعل المكان ملائمًا تجيب هذه العناصر عن سؤال "لماذا قد يهمّ المستخدم النهائي مكان معيّن؟".
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الربط يمكن أن يكون |
|
review |
ميزة تجريبية: يُرجى الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative للحصول على مزيد من التفاصيل. |
business |
ميزة تجريبية: يُرجى الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative للحصول على مزيد من التفاصيل. |
ReviewJustification
ميزة تجريبية: يُرجى الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative للحصول على مزيد من التفاصيل.
أسباب مراجعات المستخدمين يُبرز ذلك قسمًا من مراجعة المستخدم قد تهمّ المستخدم النهائي. على سبيل المثال، إذا كان طلب البحث هو "بيتزا بالفحم"، يُبرز سبب المراجعة النص ذا الصلة بطلب البحث.
تمثيل JSON |
---|
{ "highlightedText": { object ( |
الحقول | |
---|---|
highlighted |
|
review |
المراجعة التي تم إنشاء النص المميّز منها |
HighlightedText
النص الذي تم تمييزه من خلال التبرير هذه مجموعة فرعية من المراجعة نفسها. يتم وضع علامة على الكلمة المحدّدة التي سيتم تمييزها باستخدام HighlightedTextRange. قد تكون هناك عدة كلمات في النص يتم تمييزها.
تمثيل JSON |
---|
{
"text": string,
"highlightedTextRanges": [
{
object ( |
الحقول | |
---|---|
text |
|
highlighted |
قائمة نطاقات النص المميَّز |
HighlightedTextRange
نطاق النص المميّز
تمثيل JSON |
---|
{ "startIndex": integer, "endIndex": integer } |
الحقول | |
---|---|
start |
|
end |
|
BusinessAvailabilityAttributesJustification
ميزة تجريبية: يُرجى الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative للحصول على مزيد من التفاصيل. تبريرات BusinessAvailabilityAttributes يعرض ذلك بعض السمات التي يمتلكها النشاط التجاري والتي قد تهمّ المستخدم النهائي.
تمثيل JSON |
---|
{ "takeout": boolean, "delivery": boolean, "dineIn": boolean } |
الحقول | |
---|---|
takeout |
ما إذا كان المكان يوفّر طعامًا سفريًا |
delivery |
إذا كان المكان يقدّم خدمة توصيل الطلبات |
dine |
إذا كان المكان يقدّم خدمة تناول الطعام داخله |