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
}
الحقول
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

تُستخدَم لتقييد البحث على الأماكن المفتوحة حاليًا. القيمة التلقائية هي false.
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 سابقة قدِّم هذا المرجع لاسترداد الصفحة اللاحقة.

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

enum (PriceLevel)

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

boolean

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

object (LocationBias)

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

object (LocationRestriction)

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

object (EVOptions)

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

object (RoutingParameters)

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

object (SearchAlongRouteParameters)

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

boolean

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

نص الاستجابة

نموذج استجابة لـ 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 للحصول على مزيد من التفاصيل.

قائمة بالمحتوى السياقي الذي يرتبط كل إدخال فيه بالموقع المقابل له في الفهرس نفسه في حقل places يُفضّل استخدام المحتوى ذي الصلة بالموضوع 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

إذا كان المكان يقدّم خدمة تناول الطعام داخله