مقدمة
Autocomplete (جديد) هي خدمة ويب تعرض توقعات حول الأماكن وتوقعات حول طلبات البحث استجابةً لطلب HTTP. في الطلب، حدِّد سلسلة بحث نصية وحدودًا جغرافية تتحكّم في مساحة البحث.
يمكن أن تطابق ميزة "الإكمال التلقائي" (الجديدة) الكلمات الكاملة والسلاسل الفرعية من الإدخال، ما يؤدي إلى تحديد أسماء الأماكن والعناوين والرموز الزائدة. وبالتالي، يمكن للتطبيقات إرسال طلبات البحث أثناء كتابة المستخدم لها، وذلك لتقديم توقّعات فورية بشأن الأماكن وطلبات البحث.
يمكن أن تتضمّن الاستجابة من ميزة "الإكمال التلقائي (الجديدة)" نوعَين من عبارات البحث المقترَحة:
- توقّعات الأماكن: أماكن، مثل الأنشطة التجارية والعناوين ونقاط الاهتمام، استنادًا إلى سلسلة النص المُدخَل ومنطقة البحث المحدّدة يتم عرض توقعات الأماكن تلقائيًا.
- توقّعات طلبات البحث: سلاسل طلبات البحث التي تتطابق مع سلسلة النص المُدخَل ومنطقة البحث لا يتم عرض اقتراحات طلبات البحث تلقائيًا. استخدِم مَعلمة الطلب
includeQueryPredictionsلإضافة توقعات طلب البحث إلى الردّ.
على سبيل المثال، يمكنك طلب الإكمال التلقائي (جديد) باستخدام سلسلة كإدخال تتضمّن جزءًا من إدخال المستخدم، "بيتزا صقلية"، مع حصر منطقة البحث في سان فرانسيسكو، كاليفورنيا. يتضمّن الردّ بعد ذلك قائمة بتوقّعات الأماكن التي تتطابق مع سلسلة البحث ومنطقة البحث، مثل المطعم المسمّى "مطبخ بيتزا صقلية"، بالإضافة إلى تفاصيل حول المكان.
تم تصميم توقّعات الأماكن التي يتم عرضها لمساعدة المستخدم في اختيار المكان المقصود. يمكنك إرسال طلب تفاصيل المكان (جديد) للحصول على مزيد من المعلومات حول أي من توقعات الأماكن التي تم عرضها.
يمكن أن يتضمّن الردّ أيضًا قائمة بنتائج البحث المقترَحة التي تتطابق مع سلسلة البحث ومنطقة البحث، مثل "بيتزا ومعكرونة صقلية". يتضمّن كل توقّع لطلب البحث في الردّ الحقل text الذي يحتوي على سلسلة بحث نصية مقترَحة. استخدِم سلسلة الأحرف هذه كإدخال إلى البحث النصي (جديد) لإجراء بحث أكثر تفصيلاً.
تتيح لك أداة APIs Explorer إرسال طلبات مباشرة لتتمكّن من التعرّف على واجهة برمجة التطبيقات وخياراتها:
طلبات الإكمال التلقائي (جديد)
طلب الإكمال التلقائي (جديد) هو طلب 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
المَعلمات المتوافقة
المعلَمة |
الوصف |
|---|---|
سلسلة نصية للبحث (كلمات كاملة أو سلاسل فرعية أو أسماء أماكن أو عناوين أو رموز موقع مفتوح) |
|
|
تمثّل هذه المَعلمة قائمة مفصولة بفواصل تحدّد الحقول المطلوب عرضها في الاستجابة. |
لحصر النتائج بالأماكن التي تتطابق مع نوع أساسي واحد من بين ما يصل إلى خمسة أنواع أساسية محدّدة |
|
في حال صحة ذلك، يتضمّن الأنشطة التجارية التي ليس لها موقع جغرافي (الأنشطة التجارية لمنطقة الخدمة). القيمة التلقائية هي "خطأ". |
|
في حال ضبطها على "صحيح"، يتم تضمين كل من توقعات الأماكن وتوقعات طلبات البحث في الرد. القيمة التلقائية هي "خطأ". |
|
مصفوفة تتضمّن ما يصل إلى 15 رمزًا للبلد مؤلّفًا من حرفين، وذلك لحصر النتائج ببلد معيّن. |
|
إزاحة أحرف يونيكود المستندة إلى الصفر لموضع المؤشر ضمن سلسلة الإدخال، ما يؤثر في التوقعات. القيمة التلقائية هي طول الإدخال. |
|
اللغة المفضّلة (رمز IETF BCP-47) للنتائج القيمة التلقائية هي عنوان Accept-Language أو "en". |
|
تحدّد هذه السمة مساحة (دائرة أو مستطيلاً) لتوجيه نتائج البحث نحوها، ما يسمح بعرض نتائج خارج المساحة. لا يمكن استخدامها مع locationRestriction. |
|
تحدّد هذه السمة مساحة (دائرة أو مستطيلاً) لحصر نتائج البحث ضمنها. ويتم استبعاد النتائج خارج هذه المنطقة. لا يمكن استخدامها مع locationBias. |
|
نقطة البداية (خط العرض وخط الطول) المستخدَمة لحساب المسافة المستقيمة (distanceMeters) إلى الوجهات المتوقّعة. |
|
رمز المنطقة المستخدَم لتنسيق الردود والاقتراحات (مثلاً، ('uk' و'fr'). |
|
سلسلة من إنشاء المستخدم لتجميع طلبات الإكمال التلقائي في جلسة واحدة لأغراض الفوترة |
لمحة عن الردّ
تعرض ميزة "الإكمال التلقائي" (جديدة) عنصر 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
}]
},
...
}
...]
}المعلمات المطلوبة
-
input
سلسلة النص المطلوب البحث عنها. حدِّد الكلمات الكاملة والسلاسل الفرعية وأسماء الأماكن والعناوين ورموز المواقع المفتوحة. تعرض خدمة "الإكمال التلقائي (جديدة)" نتائج مطابقة محتملة استنادًا إلى هذه السلسلة، وترتّب النتائج حسب مدى صلتها بموضوع البحث.
المعلمات الاختيارية
-
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.استخدِم هذه المَعلمة لتحديد ما يصل إلى خمس قيم من النوع من الجدول A أو الجدول B. يجب أن يتطابق المكان مع إحدى قيم النوع الأساسي المحدّدة ليتم تضمينه في الرد.
يمكن أن تتضمّن هذه المَعلمة أيضًا، بدلاً من ذلك، إحدى القيمتين
(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.- يجب استخدام رموز اللغة IETF BCP-47 لتحديد اللغة المفضّلة.
-
في حال عدم توفير
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
رمز المنطقة المستخدَم لتنسيق الردّ، ويتم تحديده كقيمة مؤلّفة من حرفين لنطاق المستوى الأعلى لرمز البلد. معظم رموز نطاقات المستوى الأعلى لرمز البلد تتطابق مع رموز ISO 3166-1، مع بعض الاستثناءات البارزة. على سبيل المثال، نطاق المستوى الأعلى لرمز البلد في المملكة المتحدة هو "uk" (.co.uk)، بينما رمز ISO 3166-1 هو "gb" (وهو يشير تقنيًا إلى الكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").
تكون الاقتراحات متحيزة أيضًا استنادًا إلى رموز المناطق. تنصح Google بضبط
regionCodeوفقًا للإعدادات المفضّلة للمستخدم على مستوى المنطقة.إذا حدّدت رمز منطقة غير صالح، ستعرض واجهة برمجة التطبيقات رسالة الخطأ
INVALID_ARGUMENT. يمكن أن تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري. -
sessionToken
رموز الجلسات هي سلاسل من إنشاء المستخدمين تتتبّع طلبات الإكمال التلقائي (الجديد) باعتبارها "جلسات". تستخدم ميزة "الإكمال التلقائي" (جديدة) رموز الجلسات المميزة لتجميع مراحل طلب البحث والاختيار في عملية بحث الإكمال التلقائي التي يجريها المستخدم في جلسة منفصلة لأغراض الفوترة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة رموز الجلسات.
اختيار مَعلمات لتوجيه النتائج
يمكن أن تؤثّر مَعلمات الإكمال التلقائي (الجديدة) في نتائج البحث بشكل مختلف. يقدّم الجدول التالي اقتراحات بشأن استخدام المَعلمات استنادًا إلى النتيجة المقصودة.| المَعلمة | اقتراح الاستخدام |
|---|---|
regionCode |
يتم ضبطها وفقًا للإعدادات المفضّلة للمستخدم في المنطقة. |
includedRegionCodes |
اضبط هذا الخيار لحصر النتائج على قائمة المناطق المحدّدة. |
locationBias |
يجب استخدامها عندما تكون النتائج المفضّلة في منطقة أو حولها. إذا كان ذلك منطبقًا، حدِّد المنطقة على أنّها إطار العرض للخريطة التي يطّلع عليها المستخدم. |
locationRestriction |
استخدِم القيمة only عندما لا يجب عرض نتائج من خارج المنطقة. |
origin |
يجب استخدامها عندما يكون الهدف هو عرض مسافة خط مستقيم لكل توقع. |
أمثلة على الإكمال التلقائي (الجديد)
حصر البحث على منطقة معيّنة باستخدام locationRestriction
تحدّد السمة locationRestriction المنطقة المطلوب البحث فيها. لن يتم عرض نتائج خارج المنطقة المحدّدة. في المثال التالي، يتم استخدام locationRestriction للحدّ من
الطلب إلى دائرة يبلغ نصف قطرها 5000 متر ومركزها في سان فرانسيسكو:
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 لإضافة توقّعات طلب البحث إلى الردّ. على سبيل المثال:
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، وهو ما يحدث بالنسبة إلى التوقعات التي تبعد أقل من متر واحد عن الموقع الجغرافيoriginالمقدَّم.
ستعرض مكتبات البرامج التي تحاول قراءة الحقل distanceMeters من عنصر تم تحليله حقلاً بالقيمة 0.
لتجنُّب تضليل المستخدمين، لا تعرض مسافة صفرية
للمستخدمين.
جرّب الآن
تتيح لك أداة APIs Explorer تقديم طلبات نموذجية حتى تتمكّن من التعرّف على واجهة برمجة التطبيقات وخياراتها.
انقر على رمز واجهة برمجة التطبيقات api على يسار الصفحة.
عدِّل مَعلمات الطلب اختياريًا.
انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز ملء الشاشة fullscreen لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات".