خدمة الإكمال التلقائي (الجديدة) هي خدمة ويب تعرض مكان التنبؤات وتوقعات الاستعلام استجابةً لطلب HTTP. حدِّد نصًا في الطلب. سلسلة البحث والحدود الجغرافية التي تتحكم في منطقة البحث
يمكن أن تطابق خدمة الإكمال التلقائي (جديدة) الكلمات الكاملة و والسلاسل الفرعية للمدخل وحل أسماء الأماكن والعناوين رموز المواقع المفتوحة. وبالتالي يمكن للتطبيقات إرسال طلبات البحث مثل أنواع المستخدمين، وذلك لتوفير تنبؤات لحظيات طلب البحث وفورها.
يمكن أن يحتوي الردّ من واجهة برمجة تطبيقات الإكمال التلقائي (الجديدة) على نوعَين من التوقعات:
- توقّعات الأماكن: الأماكن، مثل الأنشطة التجارية والعناوين ونقاط الاهتمام، بناءً على سلسلة نص الإدخال المحددة ومنطقة البحث. توقعات الأماكن هي يتم إرجاعه افتراضيًا.
- توقعات طلب البحث: سلاسل طلب البحث التي تتطابق مع السلسلة النصية المدخلة و
منطقة البحث. ولا يتم عرض طلبات البحث المقترحة بشكل تلقائي. يمكنك استخدام
معلَمة طلب
includeQueryPredictions
لإضافة عبارات بحث مقترحة إلى الاستجابة.
على سبيل المثال، يمكنك استدعاء واجهة برمجة التطبيقات باستخدام كإدخال سلسلة تحتوي على إدخال جزئي للمستخدم، "piz" الصقلية، مع تقييد منطقة البحث بسان فرانسيسكو، كاليفورنيا. يحتوي الرد بعد ذلك على قائمة باقتراحات الأماكن التي تتطابق مع سلسلة البحث ومنطقة البحث، مثل مطعم باسم "مطبخ بيتزا صقلية"، إلى جانب تفاصيل عن المكان.
تم تصميم توقّعات المكان التي تم إرجاعها لعرضها على المستخدم لمساعدتك. في تحديد المكان المطلوب. يمكنك إجراء تفاصيل المكان (جديد) طلب الحصول على مزيد من المعلومات حول أي من التوقعات للأماكن التي تم إرجاعها.
ويمكن أن يتضمّن الردّ أيضًا قائمة عبارات بحث مقترحة تتطابق مع
سلسلة بحث ومنطقة بحث، مثل "بيتزا القاهرة المعكرونة". يُعد كل تنبؤ لطلب البحث في
يتضمن الرد الحقل text
الذي يحتوي على سلسلة بحث نصية مقترحة. استخدام ذلك
السلسلة كمدخل إلى
البحث النصي (جديد)
لإجراء بحث أكثر تفصيلاً.
تتيح لك مستكشف واجهات برمجة التطبيقات إجراء طلبات مباشرة حتى تتمكن من التعرّف على واجهة برمجة التطبيقات خيارات واجهة برمجة التطبيقات:
جرِّبه الآنطلبات الإكمال التلقائي (الجديدة)
طلب الإكمال التلقائي (الجديد) هو طلب HTTP POST لعنوان URL في النموذج:
https://places.googleapis.com/v1/places:autocomplete
أدخِل جميع المعلَمات في نص طلب JSON أو في العناوين كجزء من طلب POST. على سبيل المثال:
curl -X POST -d '{ "input": "pizza", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
لمحة عن الردّ
تعرض ميزة "الإكمال التلقائي" (جديد) كائن JSON كاستجابة. في الردّ:
- تحتوي المصفوفة
suggestions
على جميع الأماكن وطلبات البحث المتوقّعة بالترتيب. بناءً على صلتها بالموضوع المتصورة. يتم تمثيل كل مكان بعلامةplacePrediction
ويتم تمثيل كل طلب بحث إلى جانب حقلqueryPrediction
. - يحتوي الحقل
placePrediction
على معلومات مفصلة عن حقل واحد توقع المكان، بما في ذلك معرّف المكان ووصف النص. - يحتوي الحقل
queryPrediction
على معلومات مفصلة عن حقل واحد تنبؤ طلب البحث.
يكون كائن JSON كاملاً على النحو التالي:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 }] }, ... }, { "queryPrediction": { "text": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 }] }, ... } ...] }
المعلمات المطلوبة
-
مصدر الإدخال
السلسلة النصية المطلوب البحث فيها. حدد الكلمات الكاملة والسلاسل الفرعية أسماء الأماكن والعناوين ورموز المواقع المفتوحة. خدمة الإكمال التلقائي (الجديدة) تعرض التطابقات المرشحة بناءً على هذه السلسلة ونتائج الطلبات استنادًا إلى صلتها بالموضوع المتصورة.
المعلمات الاختيارية
-
includedPrimaryTypes
لا يمكن أن يحتوي المكان إلا على نوع أساسي واحد من الأنواع المذكورة في. Table A أو الجدول ب. على سبيل المثال: قد يكون النوع الأساسي
"mexican_restaurant"
أو"steak_house"
.تعرض واجهة برمجة التطبيقات تلقائيًا جميع الأماكن استنادًا إلى مَعلمة
input
، بغض النظر عن من قيمة النوع الأساسي المرتبطة بالمكان. تقييد النتائج لتكون محددة النوع الأساسي أو النوع الأساسي من خلال تمرير المعلمةincludedPrimaryTypes
.استخدِم هذه المَعلمة لتحديد ما يصل إلى خمس قيم أنواع من الجدول أ أو الجدول ب. يجب أن يكون المكان تطابق إحدى قيم النوع الأساسي المحددة المراد تضمينها في الرد.
وقد تتضمّن هذه المَعلمة أيضًا بدلاً من ذلك إحدى السمتَين
(regions)
أو(cities)
. فلاتر مجموعة النوع(regions)
للمناطق أو الأقسام، مثل الأحياء والرموز البريدية فلاتر مجموعة النوع(cities)
للأماكن التي يحدّدها محرّك بحث Google كمدينة.يتم رفض الطلب مع ظهور خطأ
INVALID_REQUEST
في الحالات التالية:- تم تحديد أكثر من خمسة أنواع.
- تم تحديد أي نوع بالإضافة إلى
(cities)
أو(regions)
. - تم تحديد أي أنواع غير معروفة.
-
includeQueryPredictions
إذا كانت القيمة
true
، ستتضمّن الإجابة عبارات البحث المقترحة المتعلّقة بالأماكن وطلبات البحث. الإعداد التلقائي هيfalse
، ما يعني أنّ الردّ لا يتضمّن سوى توقّعات الأماكن. -
includedRegionCodes
تضمين نتائج من قائمة المناطق المحددة فقط، والمحددة كمصفوفة يصل عددها إلى 15 عنوانًا ccTLD ("نطاق المستوى الأعلى") القيم المكونة من حرفين. في حال إسقاطها، لا يتم فرض أي قيود على الردّ. على سبيل المثال: لحصر المناطق بألمانيا وفرنسا:
"includedRegionCodes": ["de", "fr"]
إذا حددت كلاً من
locationRestriction
وincludedRegionCodes
، تكون النتائج في منطقة تقاطع الإعدادين. -
inputOffset
إزاحة أحرف يونيكود الصفرية التي تشير إلى موضع المؤشر في
input
. ويمكن أن يؤثر موضع المؤشر على عبارات البحث المقترحة التي يتم عرضها. إذا كانت فارغة، يتم ضبطها تلقائيًا على طولinput
-
languageCode
اللغة المفضّلة المطلوب عرض النتائج بها قد تكون النتائج بلغات مختلطة إذا كانت اللغة المستخدمة في
input
مختلفة عن القيمة المحددة من خلالlanguageCode
، أو إذا لم تتوفّر ترجمة للمكان الذي تم إرجاعه إلىlanguageCode
.- يجب استخدام IETF رموز اللغات BCP-47 لتحديد اللغة المفضّلة.
-
وإذا لم يتم توفير
languageCode
، ستستخدم واجهة برمجة التطبيقات القيمة المحدّدة في عنوانAccept-Language
إذا لم يتم تحديد أي منهما، يكون الإعداد الافتراضي هوen
إذا حددت رمز لغة غير صالح، ستعرض واجهة برمجة التطبيقات خطأ واحد (INVALID_ARGUMENT
). - اللغة المفضلة لها تأثير صغير في مجموعة النتائج التي تختار واجهة برمجة التطبيقات إرجاعها وترتيب إرجاعها ويؤثر ذلك أيضًا في قدرة واجهة برمجة التطبيقات على تصحيح الأخطاء الإملائية.
-
تحاول واجهة برمجة التطبيقات تقديم عنوان شارع يسهل قراءته لكل من المستخدم
السكان المحليين، بينما تعكس في نفس الوقت إدخالات المستخدم. توقعات الأماكن هي
بتنسيق مختلف بناءً على البيانات التي أدخلها المستخدم في كل طلب.
-
يتم اختيار العبارات المطابقة في مَعلمة
input
أولاً، باستخدام الأسماء التي تمت محاذاتها. باستخدام تفضيل اللغة الذي يشار إليه بالمعلمةlanguageCode
عند المتاحة، بينما يتم استخدام الأسماء التي تتطابق على أفضل نحو مع البيانات التي أدخلها المستخدم. -
يتم تنسيق عناوين الشوارع باللغة المحلية وبنص برمجي يمكن للمستخدم قراءته
عندما يكون ذلك ممكنًا، فقط بعد اختيار العبارات المطابقة لمطابقة العبارات في
مَعلمة
input
. -
ويتم إرجاع جميع العناوين الأخرى باللغة المفضّلة، بعد إدخال العبارات المطابقة
تم اختيارها لمطابقة العبارات في معلمة
input
. إذا لم يكن الاسم متاحة باللغة المفضلة، تستخدم واجهة برمجة التطبيقات أقرب تطابق.
-
يتم اختيار العبارات المطابقة في مَعلمة
تحيز الموقع أو locationRestriction
يمكنك تحديد
locationBias
أوlocationRestriction
، ولكن ليس كليهما، لتحديد منطقة البحث. التفكير فيlocationRestriction
على أنّه تحديد المنطقة التي يجب أن تكون النتائج ضمنها وlocationBias
لتحديد المنطقة التي يجب أن تكون النتائج قريبة منها ولكن يمكن أن تكون خارج المنطقة.locationBias
لتحديد منطقة للبحث. هذا الموقع بمثابة تحيز مما يعني يمكن عرض نتائج حول الموقع المحدد، بما في ذلك نتائج خارج المنطقة المحددة.
locationRestriction
لتحديد منطقة للبحث. النتائج خارج المنطقة المحدّدة ليست عاد.
تحديد المنطقة
locationBias
أوlocationRestriction
على أنّها إطار عرض مستطيل أو دائرة.يتم تحديد الدائرة بنقطة المركز ونصف القطر بالمتر. يجب أن يكون نصف القطر بين 0.0 و50000.0 بشكل شامل. القيمة التلقائية هي 0.0. معلومات تسجيل الدخول إلى
locationRestriction
يجب تعيين نصف القطر على قيمة أكبر من 0.0. بخلاف ذلك، يعرض الطلب لم يتم العثور على أي نتائج.على سبيل المثال:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
المستطيل هو إطار عرض لخطوط الطول والعرض، ويتم تمثيله في صورة اثنين بشكل قطري مقابل
low
والنقاط العالية. يٌعد إطار العرض إطارًا منطقة مغلقة، مما يعني أنها تشتمل على حدودها. حدود خط العرض يجب أن تتراوح درجة الحرارة بين -90 و90 درجة، كحدّ أقصى، يجب أن تتراوح بين -180 إلى 180 درجة، بما في ذلك:- إذا كانت
low
=high
، يتكوّن إطار العرض من هذه النقطة الفردية. - إذا كان
low.longitude
>high.longitude
، نطاق خط الطول مقلوب (يتقاطع إطار العرض مع خط الطول بزاوية 180 درجة). - إذا كانت
low.longitude
= -180 درجة وhigh.longitude
= 180 درجة، يشمل إطار العرض جميع خطوط الطول. - إذا كانت
low.longitude
= 180 درجة وhigh.longitude
= -180 درجة، نطاق خط الطول فارغ.
يجب تعبئة كل من
low
وhigh
، والمربّع الذي تمثّله لا يمكن أن يكون الحقل فارغًا. يؤدي استخدام إطار عرض فارغ إلى حدوث خطأ.على سبيل المثال، يشمل إطار العرض هذا مدينة نيويورك بالكامل:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- إذا كانت
-
الأصل
نقطة الانطلاق المطلوب منها حساب المسافة المستقيمة الوجهة (تم إرجاعها على أنّها
distanceMeters
). إذا كانت هذه القيمة محذوفة، فلن يتم إرجاع المسافة المستقيمة. يجب تحديده على أنّه إحداثيات خطوط العرض وخطوط الطول:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
رمز المنطقة المستخدَم لتنسيق الردّ، والذي يتم تحديده على أنّه ccTLD ("نطاق المستوى الأعلى") قيمة مؤلفة من حرفين. وتكون معظم رموز ccTLD متطابقة مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو "uk" (co.uk.)، لكنّ رمزها وفقًا لمعيار ISO 3166-1 هو gb. (من الناحية الفنية بالنسبة كيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").
إذا حدّدت رمز منطقة غير صالح، ستعرض واجهة برمجة التطبيقات رمز
INVALID_ARGUMENT
خطأ. ويمكن أن تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري. -
sessionToken
الرموز المميزة للجلسة هي سلاسل من إنشاء المستخدمين تتتبّع الإكمال التلقائي (جديد) كـ "جلسات". تستخدم ميزة الإكمال التلقائي (جديدة) الرموز المميّزة للجلسة تجميع مرحلتي طلب البحث والتحديد لبحث المستخدم التلقائي في جلسة منفصلة الفوترة. لمزيد من المعلومات، يُرجى مراجعة الرموز المميّزة للجلسة:
أمثلة على الإكمال التلقائي (جديدة)
استخدام حصر الموقع الجغرافي وانحياز المواقع الجغرافية
تستخدم واجهة برمجة التطبيقات انحياز عنوان IP تلقائيًا للتحكم في منطقة البحث. من خلال انحياز IP، تستخدم واجهة برمجة التطبيقات واجهة
عنوان IP للجهاز لانحياز النتائج. يمكنك اختياريًا استخدام
locationRestriction
أو locationBias
، ولكن ليس كليهما، لتحديد منطقة للبحث.
يحدّد locationRestriction
المنطقة المطلوب البحث فيها. النتائج خارج المنطقة المحدّدة
لا يتم إرجاعها. في المثال التالي، يمكنك استخدام locationRestriction
لتقييد
إلى دائرة يبلغ طولها 5000 متر في نصف قطر يركز على سان فرانسيسكو:
curl -X POST -d '{ "input": "Amoeba", "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
جميع النتائج الواردة ضمن المناطق المحدّدة مضمّنة في المصفوفة suggestions
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "store", "point_of_interest", "electronics_store" ] } } ] }
باستخدام locationBias
، يعمل الموقع بوصفه تحيزًا، ما يعني أن النتائج حول
يمكن عرض موقع محدد، بما في ذلك النتائج خارج المنطقة المحددة. في المرحلة التالية
على سبيل المثال، إذا غيّرت الطلب لاستخدام locationBias
:
curl -X POST -d '{ "input": "Amoeba", "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
تحتوي النتائج الآن على العديد من العناصر، بما في ذلك النتائج خارج النطاق الجغرافي الذي يبلغ 5000 متر:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "store", "establishment", "home_goods_store" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "establishment", "home_goods_store", "store" ] } }, ... ] }
استخدام التضمينات الأساسية المضمّنة
استخدم المعلمة includedPrimaryTypes
لتحديد ما يصل إلى خمس قيم أنواع من
الجدول أ،
الجدول ب،
أو (regions)
فقط أو (cities)
فقط. يجب أن يطابق المكان أحد الأماكن المحددة
قيم النوع الأساسي المراد تضمينها في الرد.
في المثال التالي، يمكنك تحديد سلسلة input
من
"كرة القدم" واستخدِم مَعلمة includedPrimaryTypes
لحصر النتائج
المنشآت من النوع "sporting_goods_store"
:
curl -X POST -d '{ "input": "Soccer", "includedPrimaryTypes": ["sporting_goods_store"], "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
إذا لم تستخدم المَعلمة includedPrimaryTypes
، يمكن أن تتضمّن النتائج
المنشآت من النوع الذي لا تريده، مثل "athletic_field"
.
طلب عبارات بحث مقترحة
ولا يتم عرض طلبات البحث المقترحة بشكل تلقائي. استخدام includeQueryPredictions
إضافة تنبؤات طلب البحث إلى الرد. على سبيل المثال:
curl -X POST -d '{ "input": "Amoeba", "includeQueryPredictions": true, "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
تتضمّن المصفوفة suggestions
الآن كلاً من التوقّعات المتعلقة بالأماكن وعبارات البحث المقترَحة.
كما هو موضّح أعلاه في قسم لمحة عن الردّ. كل عبارة بحث مقترحة
يتضمّن الحقل text
الذي يحتوي على سلسلة البحث عن النص المقترَح. يمكنك إجراء
البحث النصي (جديد)
طلب للحصول على مزيد من المعلومات حول أي من توقعات طلب البحث المعروضة.
استخدام المصدر
في هذا المثال، أدرِج origin
في الطلب كإحداثيات لخط العرض وخط الطول.
عند تضمين origin
، تتضمّن واجهة برمجة التطبيقات الحقل distanceMeters
في
الاستجابة التي تحتوي على مسافة الخط المستقيم من origin
إلى الوجهة.
يحدّد هذا المثال الأصل في وسط سان فرانسيسكو:
curl -X POST -d '{ "input": "Amoeba", "origin": { "latitude": 37.7749, "longitude": -122.4194 }, "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
يتضمن الرد الآن distanceMeters
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "point_of_interest", "store", "electronics_store" ], "distanceMeters": 3012 } } ] }
جرّب الآن
يتيح لك "مستكشف واجهات برمجة التطبيقات" تقديم طلبات نموذجية حتى تتمكن من الإلمام بخيارات واجهة برمجة التطبيقات وواجهة برمجة التطبيقات.
- انقر على رمز واجهة برمجة التطبيقات،
، على الجانب الأيمن من الصفحة.
- يمكنك اختياريًا توسيع عرض المَعلمات العادية وضبطها
المَعلمة
fields
إلى قناع الحقل. - يمكنك تعديل نص الطلب اختياريًا.
- انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهة برمجة التطبيقات"، حدد رمز التوسيع،
، لتوسيع نافذة مستكشف واجهة برمجة التطبيقات