- طلب 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 |
مطلوب. سلسلة النصوص المطلوب البحث فيها. |
location |
اختياريّ. توجيه النتائج نحو موقع جغرافي محدّد يجب ضبط سمة واحدة على الأقل من |
location |
اختياريّ. حصر النتائج بموقع جغرافي محدّد يجب ضبط قيمة واحدة كحدّ أقصى من |
included |
اختياريّ. نوع المكان الأساسي المُدرَج (مثل "مطعم" أو "محطة_غاز") في أنواع الأماكن (https://developers.google.com/maps/documentation/places/web-service/place-types)، أو |
included |
اختياريّ. يمكنك تضمين النتائج في المناطق المحدّدة فقط، والمحدّدة على أنّها رموز مناطق مؤلفة من حرفَين ومؤلفة من حرفَين كحد أقصى. ولن تفرض مجموعة فارغة قيودًا على النتائج. إذا تم ضبط كل من |
language |
اختياريّ. اللغة التي يتم عرض النتائج بها الإعداد التلقائي هو en-US. قد تكون النتائج بلغات مختلطة إذا كانت اللغة المستخدَمة في |
region |
اختياريّ. تمثّل هذه السمة رمز المنطقة، ويتم تحديده كرمز منطقة مؤلف من حرفين CLDR. ويؤثر ذلك في تنسيق العنوان وترتيب النتائج، وقد يؤثر في النتائج التي يتم عرضها. ولا يؤدي ذلك إلى حصر النتائج بالمنطقة المحدّدة. لتقييد النتائج على منطقة معيّنة، استخدِم |
origin |
اختياريّ. نقطة المصدر التي يتم من خلالها احتساب المسافة الجيوديسية إلى الوجهة (يتم عرضها على النحو التالي: |
input |
اختياريّ. إزاحة حرف Unicode إذا كان الحقل فارغًا، يتم ضبط الطول تلقائيًا على |
include |
اختياريّ. إذا كانت القيمة هي true، ستتضمّن الإجابة كلاً من توقّعات المكان والاستعلام. بخلاف ذلك، لن يعرض الردّ سوى توقعات الأماكن. |
session |
اختياريّ. سلسلة تحدد جلسة الإكمال التلقائي لأغراض الفوترة. يجب أن تكون سلسلة base64 آمنة لعنوان URL واسم الملف، ويجب ألا يزيد طولها عن 36 حرفًا ASCII. وخلاف ذلك، سيتم عرض خطأ ضياء_فياكن. تبدأ الجلسة عندما يبدأ المستخدم في كتابة طلب بحث، وتنتهي عند اختيار مكان وإجراء استدعاء لإجراء "تفاصيل المكان" أو "التحقّق من صحة العنوان". يمكن أن تحتوي كل جلسة على طلبات بحث متعددة، متبوعة بطلب واحد من طلبات "تفاصيل المكان" أو "التحقّق من العنوان". يجب أن تنتمي بيانات الاعتماد المستخدَمة لكل طلب ضمن جلسة إلى مشروع Google Cloud Console نفسه. بعد انتهاء الجلسة، لن يعود الرمز المميّز صالحًا، ويجب أن ينشئ تطبيقك رمزًا مميّزًا جديدًا لكل جلسة. في حال حذف المَعلمة ننصحك باتّباع الإرشادات التالية:
|
include |
اختياريّ. تضمين الأنشطة التجارية التي تعمل في منطقة خدمة فقط إذا تم ضبط الحقل على true النشاط التجاري لمنطقة الخدمة هو نشاط تجاري يمكنه زيارة العملاء أو توصيل الخدمة إليهم مباشرةً، ولكن لا يوفّر الخدمة في موقعه الجغرافي. على سبيل المثال، الأنشطة التجارية مثل خدمات التنظيف أو السباكة. لا تتوفّر لهذه الأنشطة التجارية عناوين جغرافية أو مواقع جغرافية على "خرائط Google". لن تعرض ميزة "الأماكن" حقولًا تشمل |
نص الاستجابة
نموذج استجابة لـ places.الإكمال التلقائي.
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
تمثيل JSON |
---|
{
"suggestions": [
{
object ( |
الحقول | |
---|---|
suggestions[] |
يحتوي على قائمة بالاقتراحات، ويتم ترتيبها تنازليًا حسب مدى صلة كل اقتراح بالبحث. |
LocationBias
المنطقة التي تريد البحث فيها. قد تكون النتائج متحيّزة في المنطقة المحدّدة.
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الاتحاد يمكن أن يكون |
|
rectangle |
إطار عرض محدّد من خلال زاوية شمال شرقية وجنوب غربية |
circle |
دائرة محدّدة بنقطة مركزية ونصف قطر |
LocationRestriction
المنطقة التي تريد البحث فيها. ستقتصر النتائج على المنطقة المحدّدة.
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الاتحاد يمكن أن يكون |
|
rectangle |
إطار عرض محدّد من خلال زاوية شمال شرقية وجنوب غربية |
circle |
دائرة محددة بنقطة مركزية ونصف قطر. |
اقتراح
نتيجة اقتراح للإكمال التلقائي
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الربط يمكن أن يكون |
|
place |
توقّع لمكان |
query |
توقّع لطلب بحث |
PlacePrediction
نتائج التوقّعات لعبارة بحث مقترَحة في ميزة "الإكمال التلقائي" للأماكن
تمثيل JSON |
---|
{ "place": string, "placeId": string, "text": { object ( |
الحقول | |
---|---|
place |
اسم المورد للمكان المقترَح يمكن استخدام هذا الاسم في واجهات برمجة التطبيقات الأخرى التي تقبل أسماء الأماكن. |
place |
المعرّف الفريد للمكان المقترَح ويمكن استخدام هذا المعرّف في واجهات برمجة التطبيقات الأخرى التي تقبل معرّفات الأماكن. |
text |
يحتوي على اسم يمكن لشخص عادي قراءته للنتيجة المعروضة. بالنسبة إلى نتائج المؤسسات، يكون هذا عادةً اسم النشاط التجاري وعنوانه. يُنصح باستخدام السمة قد يختلف هذا النص عن قيمة قد تكون بلغات مختلطة إذا كان الطلب |
structured |
تقسيم توقّعات الأماكن إلى نص رئيسي يحتوي على اسم المكان ونص ثانوي يحتوي على ميزات إضافية لإزالة الالتباس (مثل مدينة أو منطقة) ننصح المطوّرين الذين يريدون عرض عنصرَي واجهة مستخدم منفصلَين ولكن مرتبطَين باستخدام |
types[] |
قائمة الأنواع التي تنطبق على هذا المكان من الجدول "أ" أو الجدول "ب" في https://developers.google.com/maps/documentation/places/web-service/place-types النوع هو تصنيف لمكان معيّن. ستتشارك الأماكن ذات الأنواع المشتركة سمات مشابهة. |
distance |
طول العنصر الجيوديسي بالمتر من |
FormattableText
نص يمثّل مكانًا أو اقتراحًا لطلب بحث يمكن استخدام النص كما هو أو منسَّق.
تمثيل JSON |
---|
{
"text": string,
"matches": [
{
object ( |
الحقول | |
---|---|
text |
نص يمكن استخدامه كما هو أو تنسيقه باستخدام |
matches[] |
قائمة بنطاقات السلاسل التي تحدّد مكان مطابقة طلب الإدخال في هذه القيم هي Offsets لحرف Unicode |
StringRange
لتحديد سلسلة فرعية ضمن نص معيّن
تمثيل JSON |
---|
{ "startOffset": integer, "endOffset": integer } |
الحقول | |
---|---|
start |
القيمة المحورية المستندة إلى الصفر لحرف Unicode الأول في السلسلة (شاملة) |
end |
القيمة المضافة إلى آخر حرف Unicode (غير شاملة) وتكون مستندة إلى الصفر |
StructuredFormat
يحتوي على تفاصيل عن مكان أو توقّعات الاستعلامات في نص رئيسي ونص ثانوي.
بالنسبة إلى التوقّعات المتعلّقة بالأماكن، يحتوي النص الرئيسي على الاسم المحدّد للمكان. بالنسبة إلى التوقّعات المتعلّقة بالطلبات، يحتوي النص الرئيسي على الطلب.
يحتوي النص الثانوي على ميزات إضافية لإزالة الالتباس (مثل مدينة أو منطقة) لتحديد المكان بشكل أفضل أو تحسين الطلب.
تمثيل JSON |
---|
{ "mainText": { object ( |
الحقول | |
---|---|
main |
يمثل اسم المكان أو طلب البحث. |
secondary |
يمثّل ميزات إضافية لإزالة الالتباس (مثل مدينة أو منطقة) لتحديد المكان بشكل أفضل أو تحسين الطلب. |
QueryPrediction
نتائج التوقّع الخاصة بتوقّعات الإكمال التلقائي لطلب البحث
تمثيل JSON |
---|
{ "text": { object ( |
الحقول | |
---|---|
text |
النص المتوقّع لا يمثّل هذا النص مكانًا، بل هو طلب بحث نصي يمكن استخدامه في نقطة نهاية بحث (مثل "البحث النصي"). ننصح المطوّرين الذين يريدون عرض عنصر واحد من واجهة المستخدم باستخدام قد يكون المحتوى بلغات مختلطة إذا كان الطلبان |
structured |
تقسيم توقّعات طلب البحث إلى نص رئيسي يحتوي على طلب البحث ونص ثانوي يحتوي على ميزات إضافية لإزالة الالتباس (مثل مدينة أو منطقة) ننصح المطوّرين الذين يريدون عرض عنصرَي واجهة مستخدم منفصلَين ولكن مرتبطَين باستخدام |