- طلب HTTP
- نص الطلب
- نص الاستجابة
- LocationBias
- LocationRestriction
- اقتراح
- PlacePrediction
- FormattableText
- StringRange
- StructuredFormat
- QueryPrediction
لعرض توقعات للإدخال المحدد.
طلب HTTP
POST https://places.googleapis.com/v1/places:autocomplete
يستخدِم عنوان URL بنية تحويل ترميز gRPC.
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "input": string, "locationBias": { object ( |
الحقول | |
---|---|
input |
مطلوب. السلسلة النصية المطلوب البحث فيها. |
locationBias |
اختياريّ. يؤدي التحيز إلى موقع محدد. يجب ضبط قيمة واحدة كحدّ أقصى من |
locationRestriction |
اختياريّ. حصر النتائج في موقع محدّد يجب ضبط قيمة واحدة كحدّ أقصى من |
includedPrimaryTypes[] |
اختياريّ. تم تضمين نوع المكان الأساسي (على سبيل المثال، "مطعم" أو "محطة غاز") من الجدول أ أو الجدول ب في أنواع الأماكن (https://developers.google.com/maps/documentation/places/web-service/place-types) أو فقط (المناطق) أو (المدن فقط). لا يتم عرض مكان إلا إذا تم تضمين نوعه الأساسي في هذه القائمة. ويمكن تحديد ما يصل إلى 5 قيم. وإذا لم يتم تحديد أي أنواع، سيتم عرض جميع أنواع الأماكن. |
includedRegionCodes[] |
اختياريّ. يمكنك تضمين النتائج في المناطق المحدّدة فقط، والمحدّدة على أنّها رموز مناطق مؤلفة من حرفَين ومؤلفة من حرفَين كحد أقصى. لن تؤدي المجموعة الفارغة إلى تقييد النتائج. إذا تم ضبط كل من |
languageCode |
اختياريّ. اللغة التي يتم عرض النتائج بها. يتم ضبط الإعدادات التلقائية على en-US. قد تكون النتائج بلغات مختلطة إذا كانت اللغة المستخدمة في |
regionCode |
اختياريّ. تمثّل هذه السمة رمز المنطقة، ويتم تحديده كرمز منطقة مؤلف من حرفين CLDR. ويؤثر هذا في تنسيق العنوان وترتيب النتائج وقد يؤثر في النتائج التي يتم عرضها. لا يؤدي هذا الإجراء إلى حصر النتائج بالمنطقة المحدّدة. لحصر النتائج بمنطقة معيّنة، استخدِم |
origin |
اختياريّ. نقطة الأصل المطلوب حساب المسافة الجيوديسية منها إلى الوجهة (يتم عرضها بالصيغة |
inputOffset |
اختياريّ. إزاحة أحرف Unicode بدون قيمة وإذا كانت فارغة، سيتم ضبط القيمة التلقائية على طول |
includeQueryPredictions |
اختياريّ. إذا كانت القيمة هي true، ستتضمّن الإجابة كلاً من توقّعات المكان والاستعلام. وبخلاف ذلك، لن تعرض الاستجابة سوى تنبؤات المكان. |
sessionToken |
اختياريّ. سلسلة تحدد جلسة الإكمال التلقائي لأغراض الفوترة. يجب أن يكون عنوان URL واسم ملف متوافق مع سلسلة base64 لا يزيد طولها عن 36 حرفًا ASCII. وخلاف ذلك، يتم عرض خطأ ضياء_فياكن. تبدأ الجلسة عندما يبدأ المستخدم في كتابة طلب بحث، وتنتهي عند اختيار مكان وإجراء استدعاء لإجراء "تفاصيل المكان" أو "التحقّق من صحة العنوان". يمكن أن تحتوي كل جلسة على طلبات بحث متعددة، متبوعة بطلب واحد لتفاصيل المكان أو طلب التحقق من صحة العنوان. يجب أن تنتمي بيانات الاعتماد المستخدَمة لكل طلب خلال جلسة إلى المشروع نفسه على Google Cloud Console. وبعد انتهاء الجلسة، لا يكون الرمز المميز صالحًا؛ يجب أن ينشئ تطبيقك رمزًا مميّزًا جديدًا لكل جلسة. إذا تم حذف مَعلمة ننصح باتّباع الإرشادات التالية:
|
نص الاستجابة
نموذج استجابة لـ places.الإكمال التلقائي.
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
تمثيل JSON |
---|
{
"suggestions": [
{
object ( |
الحقول | |
---|---|
suggestions[] |
تحتوي على قائمة بالاقتراحات، مرتبة بترتيب تنازلي حسب مدى الصلة بالموضوع. |
LocationBias
المنطقة التي تريد البحث فيها. قد تكون النتائج متحيزة حول المنطقة المحددة.
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الاتحاد يمكن أن يكون |
|
rectangle |
إطار عرض محدد من خلال زاوية شمالية شرقية وزاوية جنوبية غربية. |
circle |
دائرة محددة بنقطة مركزية ونصف قطر. |
LocationRestriction
المنطقة التي تريد البحث فيها. ستقتصر النتائج على المنطقة المحددة.
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الاتحاد يمكن أن يكون |
|
rectangle |
إطار عرض محدد من خلال زاوية شمالية شرقية وزاوية جنوبية غربية. |
circle |
دائرة محددة بنقطة مركزية ونصف قطر. |
اقتراح
نتيجة اقتراح إكمال تلقائي
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الاتحاد يمكن أن يكون |
|
placePrediction |
توقع لمكان ما. |
queryPrediction |
توقّع لطلب بحث |
PlacePrediction
نتائج التوقّعات لتوقّعات الإكمال التلقائي لمكان
تمثيل JSON |
---|
{ "place": string, "placeId": string, "text": { object ( |
الحقول | |
---|---|
place |
اسم المورد للمكان المقترَح. يمكن استخدام هذا الاسم في واجهات برمجة تطبيقات أخرى تقبل أسماء الأماكن. |
placeId |
المعرّف الفريد للمكان المقترَح. يمكن استخدام هذا المعرّف في واجهات برمجة التطبيقات الأخرى التي تقبل أرقام تعريف الأماكن. |
text |
يحتوي على اسم يمكن لشخص عادي قراءته للنتيجة المعروضة. في ما يتعلّق بنتائج المؤسسات، يكون عادةً اسم النشاط التجاري وعنوانه. يُنصح باستخدام السمة قد يختلف هذا النص عن قيمة قد يكون بلغات مختلطة إذا كان الطلب |
structuredFormat |
تحليل لاقتراح المكان إلى نص رئيسي يحتوي على اسم المكان والنص الثانوي الذي يحتوي على عناصر مميزة إضافية (مثل مدينة أو منطقة). يُنصَح باستخدام السمة |
types[] |
قائمة الأنواع التي تنطبق على هذا المكان من الجدول "أ" أو الجدول "ب" في https://developers.google.com/maps/documentation/places/web-service/place-types. النوع هو تصنيف لمكان. سيكون هناك سمات متشابهة في الأماكن ذات الأنواع المشتركة. |
distanceMeters |
طول العنصر الجيوديسي بالمتر من |
FormattableText
نص يمثّل توقّعًا لأحد الأماكن أو طلب بحث يمكن استخدام النص كما هو أو منسَّق.
تمثيل JSON |
---|
{
"text": string,
"matches": [
{
object ( |
الحقول | |
---|---|
text |
النص الذي يمكن استخدامه كما هو أو تنسيقه باستخدام |
matches[] |
قائمة بنطاقات السلاسل التي تحدد مكان مطابقة طلب الإدخال في هذه القيم هي إزاحة أحرف يونيكود للرمز |
StringRange
تحدد هذه السمة سلسلة فرعية ضمن نص معين.
تمثيل JSON |
---|
{ "startOffset": integer, "endOffset": integer } |
الحقول | |
---|---|
startOffset |
إزاحة قائمة على الصفر لأول حرف يونيكود من السلسلة (شاملة). |
endOffset |
إزاحة قائمة على الصفر لآخر حرف يونيكود (غير شامل). |
StructuredFormat
يحتوي على تفاصيل حول توقّع المكان أو طلب البحث إلى نص رئيسي ونص ثانوي.
بالنسبة إلى توقعات الأماكن، يحتوي النص الرئيسي على الاسم المحدّد للمكان. بالنسبة إلى عبارات البحث المقترحة، يحتوي النص الرئيسي على طلب البحث.
يحتوي النص الثانوي على عناصر إضافية واضحة (مثل مدينة أو منطقة) لتحديد المكان بشكل أكبر أو تحسين طلب البحث.
تمثيل JSON |
---|
{ "mainText": { object ( |
الحقول | |
---|---|
mainText |
يمثل اسم المكان أو طلب البحث. |
secondaryText |
تمثل عناصر إضافية واضحة (مثل مدينة أو منطقة) لتحديد المكان بشكل أكبر أو تحسين طلب البحث. |
QueryPrediction
نتائج التوقّع الخاصة بتوقّعات الإكمال التلقائي لطلب البحث
تمثيل JSON |
---|
{ "text": { object ( |
الحقول | |
---|---|
text |
النص المتوقع. لا يمثل هذا النص مكانًا، بل طلب بحث نصيًا يمكن استخدامه في نقطة نهاية بحث (على سبيل المثال، البحث النصي). يُنصح باستخدام السمة قد يكون المحتوى بلغات مختلطة إذا كان الطلبان |
structuredFormat |
تقسيم لطلب البحث المتوقّع إلى نص رئيسي يحتوي على طلب البحث ونص ثانوي يحتوي على عناصر إضافية واضحة (مثل مدينة أو منطقة) يُنصَح باستخدام السمة |