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/maps-platform.places.textsearch
  • https://www.googleapis.com/auth/maps-platform.places
  • 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

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

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

object (Review)

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

object (Photo)

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

object (Justification)

مستندات إثبات ملكية المكان

التبرير

مستندات إثبات ملكية المكان تقدّم الأسباب إجابة عن السؤال حول سبب اهتمام المستخدم النهائي بمكان معيّن.

تمثيل 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)
businessAvailabilityAttributesJustification

object (BusinessAvailabilityAttributesJustification)

ReviewJustification

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

تمثيل 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

أسباب BusinessAvailabilityAttributes تعرض هذه السمة بعض السمات التي يتضمّنها النشاط التجاري والتي قد تهمّ المستخدم النهائي.

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

boolean

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

boolean

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

boolean

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