خدمة الإكمال التلقائي (الجديدة) هي خدمة ويب تعرض تنبؤات الأماكن وتوقعات طلبات البحث استجابةً لطلب 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
يمكن أن يحتوي المكان على نوع أساسي واحد فقط من الأنواع المدرَجة في الجدول (أ) أو الجدول (ب). على سبيل المثال، قد يكون النوع الأساسي
"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)، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (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على قناع الحقل. - يمكنك تعديل نص الطلب اختياريًا.
- انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز التوسيع،
، لتوسيع نافذة "مستكشف واجهة برمجة التطبيقات".