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
}
الحقول
input

string

مطلوب. سلسلة النصوص المطلوب البحث فيها.
locationBias

object (LocationBias)

اختيارية: توجيه النتائج نحو موقع جغرافي محدّد

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

object (LocationRestriction)

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

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

string

اختيارية: نوع المكان الأساسي المُدرَج (على سبيل المثال، "مطعم" أو "محطة_غاز") في أنواع الأماكن (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.

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

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

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

boolean

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

نص الاستجابة

نموذج الاستجابة لواجهة برمجة التطبيقات 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 إذا تم تحديد المطابقة حسب معايير أخرى غير مطابقة السلسلة (مثل التصحيحات الإملائية أو التحويل الصوتي).

هذه القيم هي Offsets لحرف 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 أو العكس.