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

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

عند تقسيم النتائج إلى صفحات، يجب أن تتطابق جميع المَعلمات الأخرى غير 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". لن تعرض Places API حقولاً تتضمّن 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 بالنسبة إلى طلب بحث فئوي مثل "مطاعم في مدينة نيويورك"، يكون الترتيب التلقائي هو "مدى الصلة بموضوع البحث". بالنسبة إلى طلبات البحث غير المصنّفة، مثل "Mountain View, CA"، ننصحك بترك rankPreference بدون ضبط.
DISTANCE ترتيب النتائج حسب المسافة
RELEVANCE يتم ترتيب النتائج حسب مدى صلتها بموضوع البحث. يتم تحديد نظام الترتيب حسب مجموعة الترتيب العادية.

LocationBias

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

تمثيل JSON
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of mutually exclusive fields.
}
الحقول
في ما يلي قائمة بالحقول التي يستبعد بعضها بعضًا. سيتم ضبط حقل واحد على الأكثر في الرد:
rectangle

object (Viewport)

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

circle

object (Circle)

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

نهاية الحقول التي يستبعد كلّ منها الآخر

LocationRestriction

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

تمثيل JSON
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "rectangle": {
    object (Viewport)
  }
  // End of mutually exclusive fields.
}
الحقول
في ما يلي قائمة بالحقول التي يستبعد بعضها بعضًا. سيتم ضبط حقل واحد على الأكثر في الرد:
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
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "encodedPolyline": string
  // End of mutually exclusive fields.
}
الحقول
تتضمّن نوع الخطوط المتعدّدة. يتم ضبط مخرجات Routes API تلقائيًا على encoded_polyline. في ما يلي قائمة بالحقول التي يستبعد بعضها بعضًا. سيتم ضبط حقل واحد على الأكثر في الرد:
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
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "reviewJustification": {
    object (ReviewJustification)
  },
  "businessAvailabilityAttributesJustification": {
    object (BusinessAvailabilityAttributesJustification)
  }
  // End of mutually exclusive fields.
}
الحقول
في ما يلي قائمة بالحقول التي يستبعد بعضها بعضًا. سيتم ضبط حقل واحد على الأكثر في الرد:
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

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