ميزة "الإكمال التلقائي (جديد)" هي خدمة ويب تعرض عبارات بحث مقترَحة ومقترَحات بشأن الأماكن استجابةً لطلب HTTP. في الطلب، حدِّد سلسلة بحث ملف شخصي وحدودًا جغرافية تتحكّم في منطقة البحث.
يمكن أن يتطابق ميزة "الإكمال التلقائي" (الميزات الجديدة) مع الكلمات الكاملة والسلسلة الفرعية للنص الذي يتم إدخاله، ما يؤدي إلى حلّ أسماء الأماكن والعناوين ورموز Plus Codes. وبالتالي، يمكن للتطبيقات إرسال طلبات بحث أثناء كتابة المستخدم، لتقديم توقعات فورية للأماكن وطلبات البحث.
يمكن أن يحتوي الردّ من ميزة "الإكمال التلقائي" (جديد) على نوعين من الاقتراحات:
- التوقّعات المتعلّقة بالأماكن: الأماكن، مثل الأنشطة التجارية والعناوين ونقاط الاهتمام، استنادًا إلى سلسلة نص الإدخال المحدّدة ومنطقة البحث يتم عرض توقّعات الأماكن تلقائيًا.
- التوقّعات المتعلّقة بطلبات البحث: سلاسل طلبات البحث التي تتطابق مع سلسلة النص التي تم إدخالها
ومنطقة البحث لا يتم عرض التوقّعات لطلبات البحث تلقائيًا. استخدِم مَعلمة الطلب
includeQueryPredictionsلإضافة توقّعات طلبات البحث إلى الردّ.
على سبيل المثال، يمكنك استدعاء ميزة "الإكمال التلقائي (جديد)" باستخدام سلسلة تحتوي على إدخال جزئي من المستخدِم، "بيتزا صقلية"، مع محدودية منطقة البحث إلى سان فرانسيسكو، كاليفورنيا. يحتوي الردّ بعد ذلك على قائمة بالتوقّعات المتعلّقة بالأماكن التي تتطابق مع سلسلة البحث ومنطقة البحث، مثل المطعم المُسمّى "Sicilian Pizza Kitchen"، بالإضافة إلى تفاصيل عن المكان.
تم تصميم التوقّعات المتعلّقة بالأماكن المعروضة لمساعدة المستخدم في اختيار المكان المقصود. يمكنك تقديم طلب بشأن تفاصيل الأماكن (جديد) للحصول على مزيد من المعلومات عن أيّ من التوقّعات التي تم عرضها للأماكن.
يمكن أن يحتوي الردّ أيضًا على قائمة بعبارات البحث المقترَحة التي تتطابق مع
سلسلة البحث ومنطقة البحث، مثل "بيتزا ومعكرونة صقلية". يتضمّن كل توقّع طلب بحث في الردّ على الطلبات الحقل 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
المَعلمات المتوافقة
المعلَمة |
الوصف |
|---|---|
سلسلة نصية للبحث فيها (كلمات كاملة أو سلاسل فرعية أو أسماء الأماكن أو العناوين أو رموز المواقع المفتوحة) |
|
|
قائمة مفصولة بفواصل تحدد الحقول التي سيتم عرضها في الاستجابة |
حصر النتائج على الأماكن التي تتطابق مع أحد الأنواع الأساسية المحدّدة التي يصل عددها إلى خمسة |
|
إذا كان صحيحًا، يشمل الأنشطة التجارية التي ليس لها موقع جغرافي (الأنشطة التجارية في منطقة الخدمة). القيمة التلقائية هي false. |
|
إذا كان صحيحًا، يتم تضمين كلّ من التوقّعات المتعلّقة بالأماكن والاستعلامات في ردّ العميل. القيمة التلقائية هي false. |
|
صفيف يتضمّن ما يصل إلى 15 رمزًا لبُلدان مكوّنًا من حرفَين لحصر النتائج بها |
|
إزاحة أحرف يونيكود المستندة إلى الصفر لموضع المؤشر ضمن سلسلة الإدخال، ما يؤثّر في التوقّعات القيمة التلقائية هي طول الإدخال |
|
اللغة المفضّلة (رمز IETF BCP-47) للنتائج القيمة التلقائية هي عنوان Accept-Language أو "en". |
|
تُحدِّد منطقة (دائرة أو مستطيل) لتوجيه نتائج البحث نحوها، مع السماح بعرض نتائج خارج المنطقة. لا يمكن استخدامه مع locationRestriction. |
|
تُحدِّد منطقة (دائرة أو مستطيل) لتضييق نطاق نتائج البحث. ويتم استبعاد النتائج خارج هذه المنطقة. لا يمكن استخدامه مع locationBias. |
|
نقطة المصدر (lat، long) المستخدَمة لاحتساب المسافة (distanceMeters) على خط مستقيم إلى الوجهات المتوقّعة |
|
رمز المنطقة المستخدَم لتنسيق الردّ وتحديد اتجاه الاقتراحات (مثل 'uk', 'fr'). |
|
سلسلة أنشأها المستخدم لتجميع طلبات الإكمال التلقائي في جلسة لأغراض الفوترة |
لمحة عن الردّ
تُعرِض ميزة "الإكمال التلقائي (جديد)" عنصر JSON كاستجابة. في الردّ:
- يحتوي صفيف
suggestionsعلى جميع الأماكن والأسئلة المتوقّعة بترتيب استنادًا إلى مدى صلتها بموضوع البحث. يتم تمثيل كل مكان باستخدام حقلplacePredictionويتم تمثيل كل طلب بحث باستخدام حقلqueryPrediction. - يحتوي حقل
placePredictionعلى معلومات تفصيلية حول اقتراح مكان واحد ، بما في ذلك معرّف المكان والوصف النصي. - يحتوي الحقل
queryPredictionعلى معلومات مفصّلة حول توقّع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
}]
},
...
}
...]
}المعلمات المطلوبة
-
إدخال
سلسلة النصوص المطلوب البحث فيها. حدِّد الكلمات الكاملة والسلسلة الفرعية، وأسماء الأماكن والعناوين ورموز المواقع المفتوحة. تُعرِض خدمة "الإكمال التلقائي (جديد)" المطابقات المُحتمَلة استنادًا إلى هذه السلسلة وترتيب النتائج استنادًا إلى مدى صلة كل نتيجة بطلب البحث.
المعلمات الاختيارية
-
FieldMask
حدِّد قائمة الحقول التي تريد عرضها في الاستجابة عن طريق إنشاء قناع حقل الاستجابة. نقْل قناع حقل الاستجابة إلى الطريقة باستخدام عنوان HTTP
X-Goog-FieldMask.حدِّد قائمة مفصولة بفواصل لحقول الاقتراحات التي تريد عرضها. على سبيل المثال، لاسترداد
suggestions.placePrediction.text.textوsuggestions.queryPrediction.text.textمن الاقتراح.X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text
استخدِم
*لاسترداد جميع الحقول.X-Goog-FieldMask: *
-
includedPrimaryTypes
لا يمكن أن يتضمّن المكان سوى نوع أساسي واحد من الأنواع المدرَجة في الجدول "أ" أو الجدول "ب". على سبيل المثال، قد يكون النوع الأساسي هو
"mexican_restaurant"أو"steak_house".تعرض واجهة برمجة التطبيقات تلقائيًا جميع الأماكن استنادًا إلى المَعلمة
input، بغض النظر عن قيمة النوع الأساسي المرتبطة بالمكان. يمكنك حصر النتائج على نوع أساسي معيّن أو أنواع أساسية معيّنة من خلال تمرير المَعلمةincludedPrimaryTypes.استخدِم هذه المَعلمة لتحديد ما يصل إلى خمس قيم من النوع من الجدول "أ" أو الجدول "ب". يجب أن يتطابق مكان مع إحدى قيم النوع الأساسي المحدّدة ليتم تضمينه في الردّ.
يمكن أن تتضمّن هذه المَعلمة أيضًا بدلاً من ذلك أحد الخيارَين
(regions)أو(cities). تصفِّر مجموعة أنواع(regions)المناطق أو التقسيمات، مثل الأحياء والرموز البريدية. تجمع مجموعة الأنواع(cities)الأماكن التي تحدّدها Google على أنّها مدينة.يتم رفض الطلب مع ظهور خطأ
INVALID_REQUESTفي الحالات التالية:- تم تحديد أكثر من خمسة أنواع.
- تم تحديد أي نوع بالإضافة إلى
(cities)أو(regions). - يتم تحديد أي أنواع غير معروفة.
-
includePureServiceAreaBusinesses
في حال ضبط القيمة على
true، يتضمّن الردّ الأنشطة التجارية التي تقدّم خدماتها من خلال زيارة العميل أو تسليم الخدمة إليه مباشرةً، ولكن ليس لها موقع جغرافي ثابت. في حال ضبط القيمة علىfalse، لا تعرض واجهة برمجة التطبيقات سوى الأنشطة التجارية التي لها موقع جغرافي. -
includeQueryPredictions
إذا كان
true، يتضمّن الردّ كلّ من عبارات البحث المقترَحة والمواقع الجغرافية المقترَحة. القيمة التلقائية هيfalse، ما يعني أنّ الاستجابة تتضمّن توقّعات الأماكن فقط. -
includedRegionCodes
تضمين النتائج من قائمة المناطق المحدّدة فقط، والتي يتم تحديدها كصفيف يتضمّن ما يصل إلى 15 قيمة من قيم نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD) المكوّنة من حرفَين في حال حذف هذا الحقل، لن يتم تطبيق أي قيود على الردّ. على سبيل المثال، لتقتصر المناطق على ألمانيا وفرنسا:
"includedRegionCodes": ["de", "fr"]
إذا حدّدت كلاً من
locationRestrictionوincludedRegionCodes، يتمّ عرض النتائج في منطقة تقاطع الإعدادَين. -
inputOffset
فهرس أحرف Unicode بدءًا من الصفر يشير إلى موضع المؤشر في
input. يمكن أن يؤثّر موضع المؤشر في التوقّعات التي يتم عرضها. إذا كان الحقل فارغًا، يتم ضبطه تلقائيًا على طولinput. -
languageCode
اللغة المفضّلة لعرض النتائج قد تكون النتائج بلغات مختلطة إذا كانت اللغة المستخدَمة في
inputمختلفة عن القيمة المحدّدة فيlanguageCode، أو إذا لم يكن للمكان المعروض ترجمة من اللغة المحلية إلىlanguageCode.- يجب استخدام رموز لغة BCP-47 وفق معيار IETF لتحديد اللغة المفضّلة.
-
في حال عدم تقديم
languageCode، تستخدم واجهة برمجة التطبيقات القيمة المحدّدة في عنوانAccept-Language. إذا لم يتم تحديد أيٍ من السمتَين، تكون القيمة التلقائية هيen. إذا حدّدت رمز لغة غير صالح، ستعرِض واجهة برمجة التطبيقات خطأINVALID_ARGUMENT. - يكون للّغة المفضّلة تأثير بسيط في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وترتيب عرضها. ويؤثّر ذلك أيضًا في قدرة واجهة برمجة التطبيقات على تصحيح الأخطاء الإملائية.
-
تحاول واجهة برمجة التطبيقات تقديم عنوان شارع يمكن قراءته لكل من المستخدِم
والسكان المحليين، مع عرض إدخال المستخدِم في الوقت نفسه. يتم تنسيق توقّعات الأماكن
بشكل مختلف حسب إدخال المستخدم في كل طلب.
-
يتم اختيار العبارات المطابقة في المَعلمة
inputأولاً، باستخدام الأسماء التي تتماشى مع اللغة المفضّلة التي تشير إليها المَعلمةlanguageCodeعند توفّرها، وفي حال عدم توفّرها، يتم استخدام الأسماء التي تتطابق بشكل أفضل مع إدخال المستخدم. -
يتم تنسيق عناوين الشوارع باللغة المحلية، في نص برمجي يمكن للمستخدم قراءة
محتواه، وذلك عندما يكون ذلك ممكنًا، فقط بعد اختيار عبارات مطابقة لمطابقة العبارات الواردة في المَعلمة
input. -
يتم عرض جميع العناوين الأخرى باللغة المفضّلة، بعد اختيار عبارات مطابقة
لمطابقة العبارات الواردة في المَعلمة
input. إذا لم يكن الاسم متوفرًا باللغة المفضّلة، تستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابقة.
-
يتم اختيار العبارات المطابقة في المَعلمة
locationBias أو 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) تتطابق معظم رموز نطاقات المستوى الأعلى لرمز البلد مع رموز ISO 3166-1، مع بعض الاستثناءات البارزة. على سبيل المثال، رمز المستوى الأعلى للمنطقة الجغرافية للمملكة المتحدة هو "uk" (.co.uk)، بينما رمزه وفقًا لمعيار ISO 3166-1 هو "gb" (من الناحية الفنية لجهة المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية).
تستند الاقتراحات أيضًا إلى رموز المناطق. تنصح Google بضبط
regionCodeوفقًا للإعدادات المفضّلة على مستوى المنطقة لدى المستخدم.إذا حدّدت رمز منطقة غير صالح، ستعرض واجهة برمجة التطبيقات خطأ
INVALID_ARGUMENT. يمكن أن تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري. -
sessionToken
علامات الجلسات هي سلاسل ينشئها المستخدمون وتتتبّع طلبات الإكمال التلقائي (الجديدة) على أنّها "جلسات". تستخدِم ميزة "الإكمال التلقائي (جديد)" الرموز المميّزة للجلسات بهدف تجميع مراحل الطلب والاختيار في عملية بحث الإكمال التلقائي للمستخدِم في جلسة منفصلة لأغراض الفوترة. لمزيد من المعلومات، يُرجى الاطّلاع على رموز الجلسات.
اختيار المَعلمات لتوجيه النتائج
يمكن أن تؤثّر مَعلمات "الإكمال التلقائي (جديد)" في نتائج البحث بشكلٍ مختلف. يقدّم الجدول التالي اقتراحات لاستخدام المَعلمات استنادًا إلى النتيجة المقصودة.| المَعلمة | اقتراح بشأن الاستخدام |
|---|---|
regionBias |
يتم ضبطها وفقًا للإعدادات المفضّلة للمستخدم في المنطقة. |
includedRegionCodes |
يتم ضبطه للحد من النتائج إلى قائمة المناطق المحدّدة. |
locationBias |
استخدِم هذا الخيار عندما تكون النتائج مفضّلة في منطقة معيّنة أو حولها. عند الاقتضاء، حدِّد المنطقة على أنّها مساحة العرض للخريطة التي يطّلع عليها المستخدم. |
locationRestriction |
استخدِم السمة فقط عندما لا يجب عرض نتائج خارج منطقة معيّنة. |
origin |
استخدِم هذا الخيار عندما تكون المسافة في خط مستقيم إلى كل
توقّع مقصودة. |
أمثلة على ميزة "الإكمال التلقائي" (جديد)
حصر البحث على منطقة باستخدام locationRestriction
locationRestriction تحدّد المنطقة التي سيتم البحث فيها. ولا يتم عرض النتائج خارج المنطقة المحدّدة. في المثال التالي، يتم استخدام locationRestriction لتقييد
الطلب على دائرة نصف قطرها 5, 000 متر وتتمركز في سان فرانسيسكو:
curl -X POST -d '{
"input": "Art museum",
"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/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "establishment", "museum", "point_of_interest" ] } }, { "placePrediction": { "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w", "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w", "text": { "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA", "matches": [ { "endOffset": 15 } ] }, "structuredFormat": { "mainText": { "text": "de Young Museum", "matches": [ { "endOffset": 15 } ] }, "secondaryText": { "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA" } }, "types": [ "establishment", "point_of_interest", "tourist_attraction", "museum" ] } }, /.../ ] }
يمكنك أيضًا استخدام locationRestriction لتقييد عمليات البحث على مجال عرض مستطيل. يحدّد المثال التالي الطلب بوسط مدينة سان فرانسيسكو:
curl -X POST -d '{
"input": "Art museum",
"locationRestriction": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
تتضمّن النتائج مصفوفة suggestions:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "point_of_interest", "museum", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc", "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc", "text": { "text": "International Art Museum of America, Market Street, San Francisco, CA, USA", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "structuredFormat": { "mainText": { "text": "International Art Museum of America", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "secondaryText": { "text": "Market Street, San Francisco, CA, USA" } }, "types": [ "museum", "point_of_interest", "tourist_attraction", "art_gallery", "establishment" ] } } ] }
توجيه البحث نحو منطقة معيّنة باستخدام مَعلمة 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
تتضمّن النتائج الآن المزيد من العناصر، بما في ذلك النتائج خارج نطاق 5, 000 متر:
{ "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" ] } }, ... ] }
يمكنك أيضًا استخدام locationBias لتقييد عمليات البحث على مجال عرض مستطيل. يحدّد المثال التالي الطلب بوسط مدينة سان فرانسيسكو:
curl -X POST -d '{
"input": "Amoeba",
"locationBias": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-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": [ "point_of_interest", "store", "establishment" ] } }, { "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": [ "point_of_interest", "store", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI", "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI", "text": { "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Hollywood Boulevard, Los Angeles, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, /.../ ] }
استخدام includedPrimaryTypes
استخدِم المَعلمة 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
request لإضافة توقّعات طلبات البحث إلى الردّ. على سبيل المثال:
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 } } ] }
عدم توفّر المسافة في الاستجابة
في بعض الحالات، لا يظهر distanceMeters في محتوى الردّ
، حتى إذا كان origin مضمّنًا في الطلب. قد يحدث ذلك في السيناريوهات التالية:
- لا يتم تضمين
distanceMetersفيrouteالتوقّعات. - لا يتم تضمين
distanceMetersعندما تكون قيمته0، وهو ما يحدث للتوقّعات التي تقلّ عن 1 متر عن الموقع الجغرافي المقدَّمorigin.
ستؤدي محاولة مكتبات العملاء قراءة حقل distanceMeters
من عنصر تم تحليله إلى عرض حقل بقيمة 0.
لتجنُّب تضليل المستخدمين، لا تعرض مسافة صفرية
للمستخدمين.
جرّب الآن
يتيح لك "مستكشف واجهات برمجة التطبيقات" إنشاء نماذج طلبات لكي تتمكّن من التعرّف على واجهة برمجة التطبيقات وخياراتها.
انقر على رمز واجهة برمجة التطبيقات api على يسار الصفحة.
يمكنك اختياريًا تعديل مَعلمات الطلب.
انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز ملء الشاشة fullscreen لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات".