- طلب 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 |
اختيارية: تضمين النتائج في المناطق المحدّدة فقط، والتي يتم تحديدها بما يصل إلى 15 رمزًا مكوّنًا من حرفَين للمناطق في CLDR ولن تفرض مجموعة فارغة قيودًا على النتائج. في حال ضبط كلٍّ من |
language |
اختيارية: اللغة التي يتم عرض النتائج بها الإعداد التلقائي هو en-US. قد تكون النتائج بلغات مختلطة إذا كانت اللغة المستخدَمة في |
region |
اختيارية: رمز المنطقة، المحدّد كرمز منطقة مكوّن من حرفَين وفقًا لمعايير CLDR ويؤثر ذلك في تنسيق العنوان وترتيب النتائج، وقد يؤثر في النتائج التي يتم عرضها. ولا يؤدي ذلك إلى حصر النتائج بالمنطقة المحدّدة. لتقييد النتائج على منطقة معيّنة، استخدِم |
origin |
اختيارية: نقطة المصدر التي يتم من خلالها احتساب المسافة الجيوديسية إلى الوجهة (يتم عرضها على النحو التالي: |
input |
اختيارية: إزاحة حرف Unicode إذا كان الحقل فارغًا، يتم ضبط الطول تلقائيًا على |
include |
اختيارية: إذا كانت القيمة "صحيح"، سيتضمّن الردّ كلّ من التوقّعات المتعلّقة بالأماكن وطلبات البحث. بخلاف ذلك، لن يعرض الردّ سوى توقعات الأماكن. |
session |
اختيارية: سلسلة تحدِّد جلسة الإكمال التلقائي لأغراض الفوترة يجب أن تكون سلسلة base64 آمنة لعنوان URL واسم الملف، ويجب ألا يزيد طولها عن 36 حرفًا ASCII. بخلاف ذلك، يتم عرض الخطأ INVALID_ARGUMENT. تبدأ الجلسة عندما يبدأ المستخدم كتابة طلب بحث، وتنتهي عندما يختار مكانًا ويتم إجراء مكالمة إلى "تفاصيل المكان" أو "التحقّق من العنوان". يمكن أن تحتوي كل جلسة على طلبات بحث متعددة، متبوعة بطلب واحد من طلبات "تفاصيل المكان" أو "التحقّق من العنوان". يجب أن تنتمي بيانات الاعتماد المستخدَمة لكل طلب ضمن جلسة إلى مشروع Google Cloud Console نفسه. بعد انتهاء الجلسة، لن يعود الرمز المميّز صالحًا، ويجب أن ينشئ تطبيقك رمزًا مميّزًا جديدًا لكل جلسة. في حال حذف المَعلمة ننصحك باتّباع الإرشادات التالية:
|
include |
اختيارية: تضمين الأنشطة التجارية التي تعمل في منطقة خدمة فقط إذا تم ضبط الحقل على true النشاط التجاري لمنطقة الخدمة هو نشاط تجاري يزور العملاء أو يقدّم خدماته لهم مباشرةً، ولكنّه لا يوفّر الخدمة في موقعه الجغرافي. على سبيل المثال، خدمات التنظيف أو السباكة لا تتوفّر لهذه الأنشطة التجارية عناوين جغرافية أو مواقع جغرافية على "خرائط Google". لن تعرض ميزة "الأماكن" حقولًا تشمل |
نص الاستجابة
تنسيق الردّ لواجهة برمجة التطبيقات places.autocomplete
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
تمثيل 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 |
تقسيم توقّعات طلب البحث إلى نص رئيسي يحتوي على طلب البحث ونص ثانوي يحتوي على ميزات إضافية لإزالة الالتباس (مثل مدينة أو منطقة) ننصح المطوّرين الذين يريدون عرض عنصرَين منفصلَين ولكن مرتبطَين من واجهة المستخدم باستخدام |