Method: places.searchText

البحث عن أماكن استنادًا إلى طلب بحث نصي

طلب HTTP

POST https://places.googleapis.com/v1/places:searchText

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

نص الطلب

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

تمثيل JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "rankPreference": enum (RankPreference),
  "includedType": string,
  "openNow": boolean,
  "minRating": number,
  "maxResultCount": integer,
  "pageSize": integer,
  "pageToken": string,
  "priceLevels": [
    enum (PriceLevel)
  ],
  "strictTypeFiltering": boolean,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "evOptions": {
    object (EVOptions)
  },
  "routingParameters": {
    object (RoutingParameters)
  },
  "searchAlongRouteParameters": {
    object (SearchAlongRouteParameters)
  },
  "includePureServiceAreaBusinesses": boolean,
  "includeFutureOpeningBusinesses": boolean
}
الحقول
textQuery

string

الحقل مطلوب. طلب البحث النصي للبحث النصي
languageCode

string

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

قائمة اللغات المتاحة حاليًا: https://developers.google.com/maps/faq#languagesupport.
regionCode

string

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

لمزيد من المعلومات، يُرجى الاطّلاع على https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html.

يُرجى العِلم أنّ رموز المناطق المكوّنة من 3 أرقام غير متاحة حاليًا.
rankPreference

enum (RankPreference)

كيفية ترتيب النتائج في الردّ
includedType

string

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

boolean

يُستخدَم هذا الفلتر لحصر البحث على الأماكن المفتوحة حاليًا. القيمة التلقائية هي "خطأ".
minRating

number

استبعاد النتائج التي يقل متوسط تقييم المستخدمين لها عن هذا الحدّ. يجب أن تكون القيمة الصالحة عددًا عائمًا بين 0 و5 (بما في ذلك هذين الرقمَين) بمعدل 0.5، أي [0, 0.5, 1.0, ... , 5.0] بما في ذلك هذين الرقمَين. سيتم تقريب التقييم المُدخَل إلى أقرب 0.5(السقف). على سبيل المثال، سيؤدي التقييم 0.6 إلى إزالة جميع النتائج التي تقلّ عن 1.0.
maxResultCount
(deprecated)

integer

تم إيقافها نهائيًا: يُرجى استخدام pageSize بدلاً منها.

الحدّ الأقصى لعدد النتائج التي يمكن عرضها في الصفحة الواحدة. إذا كان عدد النتائج المتاحة أكبر من maxResultCount، يتم عرض nextPageToken يمكن تمريره إلى pageToken للحصول على الصفحة التالية من النتائج في الطلبات اللاحقة. في حال إدخال القيمة 0 أو عدم إدخال أي قيمة، يتم استخدام القيمة التلقائية 20. الحد الأقصى للقيمة هو 20، وسيتم فرض القيمة 20 على القيم الأكبر من 20. ستعرض القيم السالبة الخطأ INVALID_ARGUMENT.

في حال تحديد كل من maxResultCount وpageSize، سيتم تجاهل maxResultCount.
pageSize

integer

اختياريّ. الحدّ الأقصى لعدد النتائج التي يمكن عرضها في الصفحة الواحدة. إذا كان عدد النتائج المتاحة أكبر من pageSize، يتم عرض nextPageToken يمكن تمريره إلى pageToken للحصول على الصفحة التالية من النتائج في الطلبات اللاحقة. في حال إدخال القيمة 0 أو عدم إدخال أي قيمة، يتم استخدام القيمة التلقائية 20. الحد الأقصى للقيمة هو 20، وسيتم ضبط القيم التي تزيد عن 20 على 20. ستعرض القيم السالبة الخطأ INVALID_ARGUMENT.

في حال تحديد كل من maxResultCount وpageSize، سيتم تجاهل maxResultCount.
pageToken

string

اختياريّ. رمز مميّز للصفحة تم استلامه من طلب TextSearch سابق. يجب تقديم هذا الرمز لاسترداد الصفحة التالية.

عند إجراء التقسيم على صفحات، يجب أن تتطابق جميع المَعلمات الأخرى غير pageToken وpageSize وmaxResultCount المقدَّمة إلى TextSearch مع الطلب الأوّلي الذي قدّم رمز مميز للصفحة. بخلاف ذلك، يتم عرض الخطأ INVALID_ARGUMENT.
priceLevels[]

enum (PriceLevel)

تُستخدَم لحصر البحث في الأماكن التي تم تصنيفها على أنّها ضمن مستويات أسعار معيّنة. يمكن للمستخدمين اختيار أي مجموعة من مستويات الأسعار. يتم تلقائيًا اختيار جميع مستويات الأسعار.
strictTypeFiltering

boolean

تُستخدَم لضبط فلترة صارمة للنوع في includedType. إذا تم ضبطها على "صحيح"، لن يتم عرض سوى نتائج من النوع نفسه. القيمة التلقائية هي "خطأ".
locationBias

object (LocationBias)

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

object (LocationRestriction)

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

object (EVOptions)

اختياريّ. تحديد خيارات المركبات الكهربائية القابلة للبحث في طلب البحث عن مكان
routingParameters

object (RoutingParameters)

اختياريّ. مَعلمات إضافية لتوجيه المستخدم إلى النتائج.
searchAlongRouteParameters

object (SearchAlongRouteParameters)

اختياريّ. نموذج أولي للمَعلمات الإضافية للبحث على طول مسار
includePureServiceAreaBusinesses

boolean

اختياريّ. أدرِج الأنشطة التجارية القاصرة على منطقة الخدمة إذا تم ضبط الحقل على "صحيح". المؤسسة ضمن منطقة الخدمة هي مؤسسة تقدّم خدماتها من خلال الانتقال إلى المواقع الجغرافية للعملاء أو توصيل الخدمة إليهم مباشرةً، ولكنّها لا تقدّم خدماتها لهم في عنوانها. على سبيل المثال، خدمات التنظيف أو السباكة ولا تتضمّن هذه الأنشطة التجارية عنوانًا أو موقعًا جغرافيًا على "خرائط Google". لن تعرض خدمة "أماكن" حقولاً تتضمّن location وplusCode وغيرها من الحقول ذات الصلة بالموقع الجغرافي لهذه الأنشطة التجارية.
includeFutureOpeningBusinesses

boolean

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

نص الاستجابة

بروتوكول الاستجابة الخاص بـ places.searchText

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

تمثيل JSON 
{
  "places": [
    {
      object (Place)
    }
  ],
  "routingSummaries": [
    {
      object (RoutingSummary)
    }
  ],
  "contextualContents": [
    {
      object (ContextualContent)
    }
  ],
  "nextPageToken": string,
  "searchUri": string
}
الحقول
places[]

object (Place)

قائمة بالأماكن التي تستوفي معايير البحث النصي للمستخدم
routingSummaries[]

object (RoutingSummary)

قائمة بملخّصات التوجيه، حيث يرتبط كل إدخال بالمكان المقابل له في الفهرس نفسه في الحقل places. إذا لم يتوفّر ملخّص التوجيه لأحد الأماكن، سيتضمّن إدخالاً فارغًا. ستتضمّن هذه القائمة عددًا من الإدخالات يساوي عدد الأماكن في القائمة إذا طُلب ذلك.
contextualContents[]

object (ContextualContent)

تجريبية: يمكنك الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative لمزيد من التفاصيل.

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

string

رمز مميز يمكن إرساله كـ pageToken لاسترداد الصفحة التالية. إذا تم حذف هذا الحقل أو كان فارغًا، هذا يعني أنّه لا توجد صفحات لاحقة.
searchUri

string

يتيح الرابط للمستخدم البحث باستخدام طلب البحث النصي نفسه المحدّد في الطلب على "خرائط Google".

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

يجب توفير نطاق OAuth التالي:

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

RankPreference

كيفية ترتيب النتائج في الردّ

عمليات التعداد
RANK_PREFERENCE_UNSPECIFIED بالنسبة إلى طلب بحث مصنّف مثل "مطاعم في مدينة نيويورك"، تكون "الملاءمة" هي الإعداد التلقائي. بالنسبة إلى طلبات البحث غير الفئوية، مثل "ماونتن فيو، كاليفورنيا"، ننصحك بعدم ضبط rankPreference.
DISTANCE ترتيب النتائج حسب المسافة
RELEVANCE ترتيب النتائج حسب مدى صلتها بموضوع البحث يتم تحديد ترتيب الفرز حسب حزمة الترتيب العادية.

LocationBias

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

تمثيل JSON 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
الحقول

حقل الربط type

يمكن أن يكون التعليق type إحدى القيم التالية فقط:
rectangle

object (Viewport)

مربّع مستطيل الشكل محدّد بالزاوية الشمالية الشرقية والزاوية الجنوبية الغربية يجب أن تكون rectangle.high() هي النقطة الشمالية الشرقية لمنطقة العرض المستطيلة. يجب أن تكون rectangle.low() هي النقطة الجنوبية الغربية لمنطقة عرض المستطيل. لا يمكن أن تكون قيمة rectangle.low().latitude() أكبر من rectangle.high().latitude(). سيؤدي ذلك إلى نطاق خطوط عرض فارغ. لا يمكن أن يزيد عرض إطار العرض المستطيل عن 180 درجة.
circle

object (Circle)

دائرة محدّدة بنقطة مركز ونصف قطر

LocationRestriction

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

تمثيل JSON 
{

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

حقل الربط type

يمكن أن يكون التعليق type إحدى القيم التالية فقط:
rectangle

object (Viewport)

مربّع مستطيل الشكل محدّد بالزاوية الشمالية الشرقية والزاوية الجنوبية الغربية يجب أن تكون rectangle.high() هي النقطة الشمالية الشرقية لمنطقة العرض المستطيلة. يجب أن تكون rectangle.low() هي النقطة الجنوبية الغربية لمنطقة العرض المستطيلة. لا يمكن أن تكون قيمة rectangle.low().latitude() أكبر من rectangle.high().latitude(). سيؤدي ذلك إلى نطاق خطوط عرض فارغ. لا يمكن أن يزيد عرض إطار العرض المستطيل عن 180 درجة.

EVOptions

خيارات المركبات الكهربائية القابلة للبحث في طلب البحث عن مكان

تمثيل JSON 
{
  "minimumChargingRateKw": number,
  "connectorTypes": [
    enum (EVConnectorType)
  ]
}
الحقول
minimumChargingRateKw

number

اختياريّ. الحدّ الأدنى لمعدّل الشحن المطلوب بالكيلوواط يتم استبعاد الأماكن التي تكون فيها تكلفة الشحن أقل من التكلفة المحدّدة.
connectorTypes[]

enum (EVConnectorType)

اختياريّ. تمثّل هذه السمة قائمة بأنواع وصلات المركبات الكهربائية المفضّلة. يتم استبعاد أي مكان لا يتوافق مع أي من أنواع أدوات الربط المُدرَجة.

SearchAlongRouteParameters

تحدّد هذه السمة خطًا متعدد الأضلاع تم حسابه مسبقًا من Routes API، ويحدّد المسار المطلوب البحث عنه. يشبه البحث على طول مسار استخدام خيار الطلب locationBias أو locationRestriction لتفضيل نتائج البحث. في المقابل، يتيح لك هذا الخيار تحديد مسار رحلة لتوجيه نتائج البحث، بينما يتيح لك الخياران locationBias وlocationRestriction تحديد منطقة لتوجيه نتائج البحث.

ليس هناك ما يضمن ظهور النتائج على طول المسار المقدَّم، بل يتم ترتيبها ضمن منطقة البحث المحدّدة بواسطة الخط المتعدد، ويمكن أيضًا ترتيبها حسب locationBias أو locationRestriction استنادًا إلى الحد الأدنى من أوقات التحويلات عن المسار من نقطة الانطلاق إلى الوجهة. قد تكون النتائج على طول مسار بديل، خاصةً إذا لم يحدّد الخط المتعدد الأضلاع المقدَّم مسارًا مثاليًا من نقطة البداية إلى الوجهة.

تمثيل JSON 
{
  "polyline": {
    object (Polyline)
  }
}
الحقول
polyline

object (Polyline)

الحقل مطلوب. الخطوط المتعددة للمسار

خط متعدد

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

تمثيل JSON 
{

  // Union field polyline_type can be only one of the following:
  "encodedPolyline": string
  // End of list of possible types for union field polyline_type.
}
الحقول
حقل الربط polyline_type تضم هذه السمة نوع الخط المتعدد. يكون الناتج التلقائي لواجهة Routes API هو encoded_polyline. يمكن أن يكون التعليق polyline_type إحدى القيم التالية فقط:
encodedPolyline

string

خط متعدّد الأضلاع مشفّر، كما تعرضه Routes API تلقائيًا اطّلِع على أداتَي الترميز وفك الترميز.

ContextualContent

تجريبية: يمكنك الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative لمزيد من التفاصيل.

المحتوى ذو الصلة بطلب البحث عن المكان

تمثيل JSON 
{
  "reviews": [
    {
      object (Review)
    }
  ],
  "photos": [
    {
      object (Photo)
    }
  ],
  "justifications": [
    {
      object (Justification)
    }
  ]
}
الحقول
reviews[]

object (Review)

قائمة بالمراجعات حول هذا المكان، وهي مراجعات سياقية ذات صلة بطلب البحث عن المكان
photos[]

object (Photo)

معلومات (بما في ذلك المراجع) حول صور هذا المكان، وهي معلومات سياقية ذات صلة بطلب البحث عن المكان
justifications[]

object (Justification)

تجريبية: يمكنك الاطّلاع على 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 justification can be only one of the following:
  "reviewJustification": {
    object (ReviewJustification)
  },
  "businessAvailabilityAttributesJustification": {
    object (BusinessAvailabilityAttributesJustification)
  }
  // End of list of possible types for union field justification.
}
الحقول

حقل الربط justification

يمكن أن يكون التعليق justification إحدى القيم التالية فقط:
reviewJustification

object (ReviewJustification)

تجريبية: يمكنك الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative لمزيد من التفاصيل.
businessAvailabilityAttributesJustification

object (BusinessAvailabilityAttributesJustification)

تجريبية: يمكنك الاطّلاع على 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 (HighlightedText)
  },
  "review": {
    object (Review)
  }
}
الحقول
highlightedText

object (HighlightedText)
review

object (Review)

تمثّل هذه السمة المراجعة التي تم إنشاء النص المميّز منها.

HighlightedText

النص الذي تم تمييزه بسبب الضبط هذا جزء من المراجعة نفسها. يتم تحديد الكلمة المطلوب تمييزها باستخدام HighlightedTextRange. قد يتضمّن النص الذي يتم تمييزه عدة كلمات.

تمثيل JSON 
{
  "text": string,
  "highlightedTextRanges": [
    {
      object (HighlightedTextRange)
    }
  ]
}
الحقول
text

string
highlightedTextRanges[]

object (HighlightedTextRange)

قائمة بنطاقات النص المميَّز

HighlightedTextRange

نطاق النص المميّز

تمثيل JSON 
{
  "startIndex": integer,
  "endIndex": integer
}
الحقول
startIndex

integer
endIndex

integer

BusinessAvailabilityAttributesJustification

تجريبية: يمكنك الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative لمزيد من التفاصيل. أسباب BusinessAvailabilityAttributes تعرض هذه السمة بعض السمات التي يتضمّنها النشاط التجاري والتي قد تهمّ المستخدم النهائي.

تمثيل JSON 
{
  "takeout": boolean,
  "delivery": boolean,
  "dineIn": boolean
}
الحقول
takeout

boolean

تُستخدَم لتحديد ما إذا كان المكان يقدّم طعامًا سفريًا.
delivery

boolean

تُستخدَم لتحديد ما إذا كان المكان يقدّم خدمة توصيل الطلبات.
dineIn

boolean

تُستخدَم لتحديد ما إذا كان المكان يوفّر خدمة الجلوس في المطعم.