- طلب HTTP
- نص الطلب
- نص الاستجابة
- نطاقات الأذونات
- RankPreference
- LocationBias
- LocationRestriction
- EVOptions
- SearchAlongRouteParameters
- خطوط متعدّدة
- ContextualContent
- التبرير
- ReviewJustification
- HighlightedText
- HighlightedTextRange
- BusinessAvailabilityAttributesJustification
البحث عن الأماكن استنادًا إلى طلب بحث نصي
طلب HTTP
POST https://places.googleapis.com/v1/places:searchText
يستخدِم عنوان URL بنية تحويل الترميز إلى gRPC.
نص الطلب
يتضمن نص الطلب بيانات بالبنية التالية:
| تمثيل JSON |
|---|
{ "textQuery": string, "languageCode": string, "regionCode": string, "rankPreference": enum ( |
| الحقول | |
|---|---|
textQuery |
الحقل مطلوب. طلب البحث النصي للبحث النصي |
languageCode |
سيتم عرض تفاصيل المكان باللغة المفضّلة إذا كانت متاحة. إذا لم يتم تحديد رمز اللغة أو لم يتم التعرّف عليه، قد يتم عرض تفاصيل المكان بأي لغة، مع تفضيل اللغة الإنجليزية إذا كانت هذه التفاصيل متوفّرة. قائمة اللغات المتاحة حاليًا: https://developers.google.com/maps/faq#languagesupport. |
regionCode |
رمز البلد/المنطقة وفقًا لمعيار Unicode (CLDR) للموقع الجغرافي الذي يأتي منه الطلب تُستخدَم هذه المَعلمة لعرض تفاصيل المكان، مثل اسم المكان الخاص بالمنطقة، إذا كان متاحًا. يمكن أن تؤثّر هذه المَعلمة في النتائج استنادًا إلى القانون الساري. لمزيد من المعلومات، يُرجى الاطّلاع على https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html. يُرجى العِلم أنّ رموز المناطق المكوّنة من 3 أرقام غير متاحة حاليًا. |
rankPreference |
كيفية ترتيب النتائج في الردّ |
includedType |
نوع المكان المطلوب يمكنك الاطّلاع على القائمة الكاملة للأنواع المتوافقة على الرابط: https://developers.google.com/maps/documentation/places/web-service/place-types. يجب أن تتوافق مع نوع واحد فقط من الأنواع المضمّنة. |
openNow |
يُستخدَم لحصر البحث في الأماكن المفتوحة حاليًا. وتكون القيمة التلقائية مضبوطة على false. |
minRating |
تصفية النتائج التي يكون متوسط تقييم المستخدمين لها أقل من هذا الحدّ يجب أن تكون القيمة الصالحة عددًا عشريًا بين 0 و5 (ضمنًا) بمعدّل 0.5، أي [0، 0.5، 1.0، ...، 5.0] ضمنًا. سيتم تقريب التقييم الذي تم إدخاله إلى أقرب 0.5(الحد الأقصى). على سبيل المثال، سيؤدي التقييم 0.6 إلى استبعاد جميع النتائج التي يقل تقييمها عن 1.0. |
maxResultCount |
تم إيقاف هذه السياسة نهائيًا، لذا يُرجى استخدام سياسة الحد الأقصى لعدد النتائج التي يمكن عرضها في كل صفحة. إذا كان عدد النتائج المتاحة أكبر من في حال تحديد كل من |
pageSize |
اختيارية: الحد الأقصى لعدد النتائج التي يمكن عرضها في كل صفحة. إذا كان عدد النتائج المتاحة أكبر من في حال تحديد كل من |
pageToken |
اختيارية: رمز مميّز للصفحة، يتم تلقّيه من طلب TextSearch سابق. يجب تقديم هذه القيمة لاسترداد الصفحة التالية. عند تقسيم النتائج إلى صفحات، يجب أن تتطابق جميع المَعلمات الأخرى غير |
priceLevels[] |
يُستخدَم هذا المعيار لحصر البحث في الأماكن التي تم وضع علامة عليها كمستويات أسعار معيّنة. يمكن للمستخدمين اختيار أي مجموعات من مستويات الأسعار. يتم تلقائيًا اختيار جميع مستويات الأسعار. |
strictTypeFiltering |
يُستخدَم لضبط فلترة صارمة للنوع في includedType. في حال ضبط هذه السياسة على "صحيح"، سيتم عرض النتائج من النوع نفسه فقط. القيمة التلقائية هي "خطأ". |
locationBias |
تمثّل هذه السمة المنطقة المطلوب البحث فيها. يُستخدم هذا الموقع الجغرافي كعامل تحيز، ما يعني أنّه قد يتم عرض النتائج حول الموقع الجغرافي المحدّد. لا يمكن ضبطه مع locationRestriction. |
locationRestriction |
تمثّل هذه السمة المنطقة المطلوب البحث فيها. يُعدّ هذا الموقع الجغرافي قيدًا، ما يعني أنّه لن يتم عرض النتائج خارج الموقع الجغرافي المحدّد. لا يمكن ضبطه مع locationBias. |
evOptions |
اختيارية: ضبط خيارات المركبات الكهربائية القابلة للبحث في طلب البحث عن الأماكن |
routingParameters |
اختيارية: مَعلمات إضافية لتوجيه النتائج |
searchAlongRouteParameters |
اختيارية: مَعلمات إضافية للبحث على طول مسار معيّن |
includePureServiceAreaBusinesses |
اختيارية: يتم تضمين المؤسسات التي تقدّم خدماتها ضمن منطقة الخدمة فقط إذا تم ضبط الحقل على "صحيح". المؤسسة ضمن منطقة الخدمة فقط هي مؤسسة تقدّم خدماتها من خلال الانتقال إلى المواقع الجغرافية للعملاء أو توصيل الخدمة إليهم مباشرةً، ولكنّها لا تقدّم خدماتها لهم في عنوانها. على سبيل المثال، خدمات التنظيف أو السباكة ولا تملك هذه المؤسسات عنوانًا جغرافيًا أو موقعًا جغرافيًا على "خرائط Google". لن تعرض Places API حقولاً تتضمّن |
includeFutureOpeningBusinesses |
اختيارية: إذا كانت القيمة "صحيح"، يتم تضمين المؤسسات التي لم يتم افتتاحها بعد ولكن سيتم افتتاحها في المستقبل. |
نص الاستجابة
الاستجابة الأولية لـ places.searchText.
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
| تمثيل JSON |
|---|
{ "places": [ { object ( |
| الحقول | |
|---|---|
places[] |
قائمة بالأماكن التي تستوفي معايير البحث النصي للمستخدم |
routingSummaries[] |
قائمة بملخّصات المسارات حيث يرتبط كل إدخال بالمكان المقابل في الفهرس نفسه في الحقل |
contextualContents[] |
ميزة تجريبية: لمزيد من التفاصيل، يُرجى الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative. قائمة بالمحتوى السياقي حيث يرتبط كل إدخال بالمكان المقابل في الفهرس نفسه في حقل الأماكن. يُفضَّل المحتوى ذو الصلة بـ |
nextPageToken |
رمز مميّز يمكن إرساله كـ |
searchUri |
يتيح الرابط للمستخدم البحث باستخدام طلب البحث النصي نفسه المحدّد في الطلب على "خرائط Google". |
نطاقات الأذونات
يتطلب أحد نطاقات OAuth التالية:
https://www.googleapis.com/auth/maps-platform.places.textsearchhttps://www.googleapis.com/auth/maps-platform.placeshttps://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 ( |
| الحقول | |
|---|---|
| في ما يلي قائمة بالحقول التي يستبعد بعضها بعضًا. سيتم ضبط حقل واحد على الأكثر في الرد: | |
rectangle |
مربّع مستطيل تحدّده الزاوية الشمالية الشرقية والزاوية الجنوبية الغربية يجب أن تكون السمة |
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 ( |
| الحقول | |
|---|---|
| في ما يلي قائمة بالحقول التي يستبعد بعضها بعضًا. سيتم ضبط حقل واحد على الأكثر في الرد: | |
rectangle |
مربّع مستطيل تحدّده الزاوية الشمالية الشرقية والزاوية الجنوبية الغربية يجب أن تكون السمة |
| نهاية الحقول التي يستبعد كلّ منها الآخر | |
EVOptions
خيارات المركبات الكهربائية القابلة للبحث في طلب البحث عن الأماكن
| تمثيل JSON |
|---|
{
"minimumChargingRateKw": number,
"connectorTypes": [
enum ( |
| الحقول | |
|---|---|
minimumChargingRateKw |
اختيارية: الحدّ الأدنى المطلوب لمعدّل الشحن بالكيلوواط تتم فلترة الأماكن التي يكون معدّل الشحن فيها أقل من المعدّل المحدّد. |
connectorTypes[] |
اختيارية: قائمة بأنواع وصلات المركبات الكهربائية المفضّلة تتم فلترة أي مكان لا يتوافق مع أي من أنواع الموصلات المدرَجة. |
SearchAlongRouteParameters
يحدّد خطًا متعدّدًا تم حسابه مسبقًا من Routes API يحدّد المسار المطلوب البحث فيه. يشبه البحث على طول مسار استخدام خيار الطلب locationBias أو locationRestriction لتوجيه نتائج البحث. ومع ذلك، في حين أنّ الخيارَين locationBias وlocationRestriction يتيحان لك تحديد منطقة لتفضيل نتائج البحث، يتيح لك هذا الخيار تفضيل النتائج على طول مسار الرحلة.
لا نضمن أن تكون النتائج على طول المسار المقدَّم، بل يتم ترتيبها ضمن منطقة البحث المحدّدة من خلال الخطوط المتعدّدة، واختياريًا، من خلال locationBias أو locationRestriction استنادًا إلى الحدّ الأدنى من أوقات الانعطاف من نقطة الانطلاق إلى الوجهة. قد تكون النتائج على طول مسار بديل، خاصةً إذا لم يحدّد الشكل المتعدّد الخطوط المقدَّم مسارًا مثاليًا من نقطة الانطلاق إلى الوجهة.
| تمثيل JSON |
|---|
{
"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 |
خطوط متعدّدة مرمّزة، كما تعرضها واجهة برمجة التطبيقات Routes API تلقائيًا يمكنك الاطّلاع على أداتَي الترميز وفك الترميز. |
| نهاية الحقول التي يستبعد كلّ منها الآخر | |
ContextualContent
محتوى يتعلّق بطلب البحث عن المكان
| تمثيل JSON |
|---|
{ "reviews": [ { object ( |
| الحقول | |
|---|---|
reviews[] |
قائمة بالمراجعات حول هذا المكان، وهي سياقية لطلب البحث عن المكان. |
photos[] |
معلومات (بما في ذلك المراجع) عن صور هذا المكان، تكون سياقية لطلب البحث عن المكان |
justifications[] |
أسباب اختيار المكان |
التبرير
أسباب اختيار المكان تُجيب التبريرات عن السؤال حول سبب اهتمام المستخدم النهائي بمكان معيّن.
| تمثيل 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 |
|
| نهاية الحقول التي يستبعد كلّ منها الآخر | |
ReviewJustification
مُبرّرات مراجعات المستخدمين يؤدي ذلك إلى تمييز قسم من مراجعة المستخدم قد يثير اهتمام المستخدم النهائي. على سبيل المثال، إذا كان طلب البحث هو "بيتزا على الحطب"، ستُبرز عبارة توضيح المراجعة النص ذي الصلة بطلب البحث.
| تمثيل JSON |
|---|
{ "highlightedText": { object ( |
| الحقول | |
|---|---|
highlightedText |
|
review |
المراجعة التي تم إنشاء النص المميّز منها |
HighlightedText
النص الذي تم تمييزه في سبب الظهور وهذه مجموعة فرعية من المراجعة نفسها. يتم تحديد الكلمة المحددة التي سيتم تمييزها بواسطة HighlightedTextRange. قد تكون هناك عدة كلمات في النص يتم تمييزها.
| تمثيل JSON |
|---|
{
"text": string,
"highlightedTextRanges": [
{
object ( |
| الحقول | |
|---|---|
text |
|
highlightedTextRanges[] |
قائمة بنطاقات النص المميَّز |
HighlightedTextRange
نطاق النص المميّز
| تمثيل JSON |
|---|
{ "startIndex": integer, "endIndex": integer } |
| الحقول | |
|---|---|
startIndex |
|
endIndex |
|
BusinessAvailabilityAttributesJustification
أسباب BusinessAvailabilityAttributes يعرض هذا بعض السمات التي يمتلكها النشاط التجاري والتي قد تهم المستخدم النهائي.
| تمثيل JSON |
|---|
{ "takeout": boolean, "delivery": boolean, "dineIn": boolean } |
| الحقول | |
|---|---|
takeout |
إذا كان المكان يقدّم طعامًا سفريًا |
delivery |
تشير إلى ما إذا كان المكان يوفّر خدمة توصيل الطلبات. |
dineIn |
ما إذا كان المكان يوفّر خدمة الجلوس في المطعم |