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

string

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

string

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

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

string

رمز البلد/المنطقة يونيكود (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. سيؤدي ذلك إلى عرض رسالة الخطأ POINTS_{6/} في القيم السلبية.

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

integer

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

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

string

اختياريّ. رمز مميز للصفحة تم استلامه من مكالمة سابقة عبر TextSearch. يُرجى توفير هذا الحقل لاسترداد الصفحة التالية.

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

enum (PriceLevel)

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

boolean

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

object (LocationBias)

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

object (LocationRestriction)

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

object (EVOptions)

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

نص الاستجابة

نموذج الرد لـ places.searchText.

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

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

object (Place)

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

object (ContextualContent)

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

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

string

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

RankPreference

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

عمليات التعداد
RANK_PREFERENCE_UNSPECIFIED بالنسبة إلى استعلام فئوي مثل "مطاعم في مدينة نيويورك"، يكون RELEVANCE الافتراضي هو. بالنسبة إلى طلبات البحث غير الفئوية، مثل "Mountain View, CA"، ننصحك بترك المفضلة بدون ضبط.
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)

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

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

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

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

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