Method: places.autocomplete

تعرض هذه الطريقة التوقعات الخاصة بالمدخلات المحدّدة.

طلب HTTP

POST https://places.googleapis.com/v1/places:autocomplete

يستخدِم عنوان URL بنية تحويل الترميز إلى gRPC.

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

تمثيل JSON 
{
  "input": string,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "includedPrimaryTypes": [
    string
  ],
  "includedRegionCodes": [
    string
  ],
  "languageCode": string,
  "regionCode": string,
  "origin": {
    object (LatLng)
  },
  "inputOffset": integer,
  "includeQueryPredictions": boolean,
  "sessionToken": string,
  "includePureServiceAreaBusinesses": boolean,
  "includeFutureOpeningBusinesses": boolean
}
الحقول
input

string

الحقل مطلوب. سلسلة النص المطلوب البحث عنها.
locationBias

object (LocationBias)

اختياريّ. تحيز النتائج لموقع جغرافي محدّد

يجب ضبط سمة واحدة على الأكثر من locationBias أو locationRestriction. في حال عدم ضبط أي منهما، ستكون النتائج متحيزة حسب عنوان IP، ما يعني أنّه سيتم ربط عنوان IP بموقع جغرافي غير دقيق واستخدامه كإشارة تحيز.
locationRestriction

object (LocationRestriction)

اختياريّ. لحصر النتائج بموقع جغرافي محدّد

يجب ضبط سمة واحدة على الأكثر من locationBias أو locationRestriction. في حال عدم ضبط أي منهما، ستكون النتائج متحيزة حسب عنوان IP، ما يعني أنّه سيتم ربط عنوان IP بموقع جغرافي غير دقيق واستخدامه كإشارة تحيز.
includedPrimaryTypes[]

string

اختياريّ. نوع المكان الأساسي المُدرَج (على سبيل المثال، "restaurant" أو "gas_station") في "أنواع الأماكن" (https://developers.google.com/maps/documentation/places/web-service/place-types)، أو (regions) فقط، أو (cities) فقط لا يتم عرض "مكان" إلا إذا كان نوعه الأساسي مضمّنًا في هذه القائمة. يمكن تحديد ما يصل إلى 5 قيم. في حال عدم تحديد أي أنواع، سيتم عرض جميع أنواع "الأماكن".
includedRegionCodes[]

string

اختياريّ. تضمين النتائج في المناطق المحدّدة فقط، والتي يتم تحديدها على أنّها ما يصل إلى 15 رمزًا من رموز CLDR المكوّنة من حرفَين لن تؤدي المجموعة الفارغة إلى حصر النتائج. في حال ضبط كل من locationRestriction وincludedRegionCodes، ستظهر النتائج في منطقة التقاطع.
languageCode

string

اختياريّ. اللغة التي سيتم عرض النتائج بها القيمة التلقائية هي en-US. قد تكون النتائج بلغات مختلطة إذا كانت اللغة المستخدَمة في input مختلفة عن languageCode أو إذا لم يكن للمكان المعروض ترجمة من اللغة المحلية إلى languageCode.
regionCode

string

اختياريّ. رمز المنطقة، ويتم تحديده كرمز منطقة CLDR مكوّن من حرفين يؤثر ذلك في تنسيق العناوين وترتيب النتائج، وقد يؤثر في النتائج التي يتم عرضها. لا يؤدي ذلك إلى حصر النتائج في المنطقة المحدّدة. لحصر النتائج على منطقة معيّنة، استخدِم region_code_restriction.
origin

object (LatLng)

اختياريّ. نقطة البداية التي يتم منها احتساب المسافة الجيوديسية إلى الوجهة (يتم عرضها كـ distanceMeters). في حال حذف هذه القيمة، لن يتم عرض المسافة الجيوديسية.
inputOffset

integer

اختياريّ. إزاحة حرف Unicode مستندة إلى الصفر input تشير إلى موضع المؤشر في input قد يؤثّر موضع المؤشر في التوقّعات التي يتم عرضها.

إذا كان الحقل فارغًا، يتم ضبط القيمة التلقائية على طول input.
includeQueryPredictions

boolean

اختياريّ. إذا كانت القيمة صحيحة، سيتضمّن الردّ كلاً من توقعات الأماكن وتوقعات طلبات البحث. بخلاف ذلك، لن تعرض الاستجابة سوى توقعات الأماكن.
sessionToken

string

اختياريّ. سلسلة تحدّد جلسة الإكمال التلقائي لأغراض الفوترة. يجب أن تكون سلسلة base64 آمنة لعنوان URL واسم الملف، وأن تتضمّن 36 حرفًا من أحرف ASCII كحد أقصى. بخلاف ذلك، يتم عرض الخطأ INVALID_ARGUMENT.

تبدأ الجلسة عندما يبدأ المستخدم في كتابة طلب بحث، وتنتهي عندما يختار مكانًا ويتم إجراء طلب إلى تفاصيل المكان أو Address Validation. يمكن أن تتضمّن كل جلسة طلبات بحث متعدّدة، يليها طلب واحد للحصول على تفاصيل المكان أو التحقّق من صحة العنوان. يجب أن تنتمي بيانات الاعتماد المستخدَمة في كل طلب ضمن جلسة إلى مشروع Google Cloud Console نفسه. بعد انتهاء الجلسة، لن يكون الرمز المميز صالحًا، ويجب أن ينشئ تطبيقك رمزًا مميزًا جديدًا لكل جلسة. في حال حذف المَعلمة sessionToken أو إعادة استخدام رمز مميّز للجلسة، سيتم تحصيل رسوم الجلسة كما لو لم يتم تقديم رمز مميّز للجلسة (سيتم تحصيل رسوم كل طلب على حدة).

ننصحك باتّباع الإرشادات التالية:

  • استخدِم الرموز المميزة للجلسات لجميع طلبات الإكمال التلقائي للأماكن.
  • إنشاء رمز مميز جديد لكل جلسة ننصح باستخدام معرّف فريد عالميًا من الإصدار 4.
  • تأكَّد من أنّ بيانات الاعتماد المستخدَمة في جميع طلبات الإكمال التلقائي للأماكن وPlace Details وAddress Validation خلال جلسة واحدة تنتمي إلى مشروع Cloud Console نفسه.
  • احرص على تمرير الرمز المميز للجلسة فريد لكل جلسة جديدة. سيؤدي استخدام الرمز المميز نفسه لأكثر من جلسة واحدة إلى تحرير فاتورة لكل طلب على حدة.
includePureServiceAreaBusinesses

boolean

اختياريّ. أدرِج الأنشطة التجارية القاصرة على منطقة الخدمة إذا تم ضبط الحقل على "صحيح". المؤسسة ضمن منطقة الخدمة هي مؤسسة تقدّم خدماتها من خلال الانتقال إلى المواقع الجغرافية للعملاء أو توصيل الخدمة إليهم مباشرةً، ولكنّها لا تقدّم خدماتها لهم في عنوانها. على سبيل المثال، خدمات التنظيف أو السباكة ولا تتضمّن هذه الأنشطة التجارية عنوانًا أو موقعًا جغرافيًا على "خرائط Google". لن تعرض خدمة "أماكن" حقولاً تتضمّن location وplusCode وغيرها من الحقول ذات الصلة بالموقع الجغرافي لهذه الأنشطة التجارية.
includeFutureOpeningBusinesses

boolean

اختياريّ. إذا كانت القيمة صحيحة، يجب تضمين الأنشطة التجارية التي لم يتم افتتاحها بعد ولكن سيتم افتتاحها في المستقبل.

نص الاستجابة

بروتوكول الردّ على places.autocomplete

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
الحقول
suggestions[]

object (Suggestion)

تحتوي على قائمة بالاقتراحات، ويتم ترتيبها ترتيبًا تنازليًا حسب مدى الصلة بالموضوع.

نطاقات الأذونات

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/cloud-platform

LocationBias

تمثّل هذه السمة المنطقة المطلوب البحث فيها. قد تكون النتائج متحيزة بشأن المنطقة المحدّدة.

تمثيل JSON 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
الحقول

حقل الربط type

يمكن أن يكون التعليق type إحدى القيم التالية فقط:
rectangle

object (Viewport)

نافذة عرض محدّدة بواسطة ركن شمالي شرقي وركن جنوبي غربي
circle

object (Circle)

دائرة محدّدة بنقطة مركزية ونصف قطر

LocationRestriction

تمثّل هذه السمة المنطقة المطلوب البحث فيها. ستقتصر النتائج على المنطقة المحدّدة.

تمثيل JSON 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
الحقول

حقل الربط type

يمكن أن يكون التعليق type إحدى القيم التالية فقط:
rectangle

object (Viewport)

نافذة عرض محدّدة بواسطة ركن شمالي شرقي وركن جنوبي غربي
circle

object (Circle)

دائرة محدّدة بنقطة مركزية ونصف قطر

اقتراح

تمثّل هذه السمة نتيجة اقتراح للإكمال التلقائي.

تمثيل JSON 
{

  // Union field kind can be only one of the following:
  "placePrediction": {
    object (PlacePrediction)
  },
  "queryPrediction": {
    object (QueryPrediction)
  }
  // End of list of possible types for union field kind.
}
الحقول

حقل الربط kind

يمكن أن يكون التعليق kind إحدى القيم التالية فقط:
placePrediction

object (PlacePrediction)

توقّع لمكان
queryPrediction

object (QueryPrediction)

توقّع لطلب بحث

PlacePrediction

نتائج عبارات البحث المقترَحة من خلال ميزة "الإكمال التلقائي للأماكن".

تمثيل JSON 
{
  "place": string,
  "placeId": string,
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  },
  "types": [
    string
  ],
  "distanceMeters": integer
}
الحقول
place

string

اسم المورد الخاص بالمكان المقترَح. يمكن استخدام هذا الاسم في واجهات برمجة التطبيقات الأخرى التي تقبل أسماء الأماكن.
placeId

string

المعرّف الفريد للمكان المقترَح. يمكن استخدام هذا المعرّف في واجهات برمجة التطبيقات الأخرى التي تقبل معرّفات الأماكن.
text

object (FormattableText)

تحتوي على الاسم الذي يمكن للمستخدم قراءته للنتيجة التي تم إرجاعها. بالنسبة إلى نتائج المؤسسات، يكون ذلك عادةً اسم النشاط التجاري وعنوانه.

يُنصح باستخدام text للمطوّرين الذين يريدون عرض عنصر واحد من عناصر واجهة المستخدم. قد يحتاج المطوّرون الذين يريدون عرض عنصرَين منفصلَين ولكن مرتبطَين في واجهة المستخدِم إلى استخدام structuredFormat بدلاً من ذلك. وهما طريقتان مختلفتان لتمثيل نتيجة توقّع بشأن مكان. يجب ألا يحاول المستخدمون تحليل structuredFormat إلى text أو العكس.

قد يختلف هذا النص عن displayName الذي تعرضه طريقة places.get.

قد تكون بلغات مختلطة إذا كانت الطلبات input وlanguageCode بلغات مختلفة أو إذا لم يكن لدى "المكان" ترجمة من اللغة المحلية إلى languageCode.
structuredFormat

object (StructuredFormat)

تقسيم لتوقّع المكان إلى نص رئيسي يتضمّن اسم المكان ونص ثانوي يتضمّن ميزات إضافية لإزالة الغموض (مثل مدينة أو منطقة)

يُنصح باستخدام structuredFormat للمطوّرين الذين يريدون عرض عنصرَين منفصلَين ولكن مرتبطَين في واجهة المستخدم. يمكن للمطوّرين الذين يريدون عرض عنصر في واجهة المستخدم استخدام text بدلاً من ذلك. وهما طريقتان مختلفتان لتمثيل نتيجة توقّع بشأن مكان. يجب ألا يحاول المستخدمون تحليل structuredFormat إلى text أو العكس.
types[]

string

قائمة بالأنواع التي تنطبق على هذا المكان من الجدول (أ) أو الجدول (ب) في https://developers.google.com/maps/documentation/places/web-service/place-types

النوع هو تصنيف للمكان. ستتشارك الأماكن التي لها أنواع مشتركة سمات متشابهة.
distanceMeters

integer

طول الخط الجيوديسي بالأمتار من origin إذا تم تحديد origin. قد لا تتم تعبئة هذا الحقل ببعض التوقعات، مثل الطرق.

FormattableText

نص يمثّل مكانًا أو اقتراحًا لطلب بحث يمكن استخدام النص كما هو أو تنسيقه.

تمثيل JSON 
{
  "text": string,
  "matches": [
    {
      object (StringRange)
    }
  ]
}
الحقول
text

string

نص يمكن استخدامه كما هو أو تنسيقه باستخدام matches
matches[]

object (StringRange)

قائمة بنطاقات السلاسل التي تحدّد موضع تطابق طلب الإدخال في text يمكن استخدام النطاقات لتنسيق أجزاء معيّنة من text. قد لا تكون السلاسل الفرعية مطابقة تمامًا لـ input إذا تم تحديد المطابقة من خلال معايير أخرى غير مطابقة السلسلة (على سبيل المثال، تصحيحات إملائية أو ترجمات صوتية).

هذه القيم هي إزاحات أحرف Unicode الخاصة بـ text. ويتم ضمان ترتيب النطاقات حسب قيم الإزاحة المتزايدة.

StringRange

تحدّد هذه الدالة سلسلة فرعية ضمن نص معيّن.

تمثيل JSON 
{
  "startOffset": integer,
  "endOffset": integer
}
الحقول
startOffset

integer

الإزاحة المستندة إلى الصفر لأول حرف Unicode في السلسلة (شاملة).
endOffset

integer

إزاحة مستندة إلى الصفر لآخر حرف Unicode (حصري).

StructuredFormat

تحتوي على تقسيم لتوقّع مكان أو استعلام إلى نص رئيسي ونص ثانوي.

بالنسبة إلى توقّعات الأماكن، يحتوي النص الرئيسي على الاسم المحدّد للمكان. بالنسبة إلى اقتراحات البحث، يحتوي النص الرئيسي على طلب البحث.

يحتوي النص الثانوي على ميزات إضافية لإزالة الغموض (مثل مدينة أو منطقة) لتحديد "المكان" بشكل أكبر أو تحسين طلب البحث.

تمثيل JSON 
{
  "mainText": {
    object (FormattableText)
  },
  "secondaryText": {
    object (FormattableText)
  }
}
الحقول
mainText

object (FormattableText)

تمثّل هذه السمة اسم المكان أو طلب البحث.
secondaryText

object (FormattableText)

تمثّل هذه السمة ميزات إضافية لإزالة الغموض (مثل مدينة أو منطقة) من أجل تحديد "المكان" بشكلٍ أفضل أو تحسين طلب البحث.

QueryPrediction

نتائج عبارات البحث المقترَحة من خلال ميزة "الإكمال التلقائي" لطلب بحث

تمثيل JSON 
{
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  }
}
الحقول
text

object (FormattableText)

النص المتوقّع لا يمثّل هذا النص مكانًا، بل هو طلب بحث نصي يمكن استخدامه في نقطة نهاية بحث (مثل "البحث النصي").

يُنصح باستخدام text للمطوّرين الذين يريدون عرض عنصر واحد من عناصر واجهة المستخدم. قد يحتاج المطوّرون الذين يريدون عرض عنصرَين منفصلَين ولكن مرتبطَين في واجهة المستخدِم إلى استخدام structuredFormat بدلاً من ذلك. وهما طريقتان مختلفتان لتمثيل توقع لطلب بحث. يجب ألا يحاول المستخدمون تحليل structuredFormat إلى text أو العكس.

قد تكون النتائج بلغات مختلطة إذا كان الطلب input وlanguageCode بلغات مختلفة أو إذا لم يتوفّر جزء من طلب البحث بترجمة من اللغة المحلية إلى languageCode.
structuredFormat

object (StructuredFormat)

تقسيم لتوقّع طلب البحث إلى نص رئيسي يتضمّن طلب البحث ونص ثانوي يتضمّن ميزات إضافية لإزالة الغموض (مثل مدينة أو منطقة)

يُنصح باستخدام structuredFormat للمطوّرين الذين يريدون عرض عنصرَين منفصلَين ولكن مرتبطَين في واجهة المستخدم. يمكن للمطوّرين الذين يريدون عرض عنصر في واجهة المستخدم استخدام text بدلاً من ذلك. وهما طريقتان مختلفتان لتمثيل توقع لطلب بحث. يجب ألا يحاول المستخدمون تحليل structuredFormat إلى text أو العكس.