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
}
الحقول
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) أو فقط (المناطق) أو (المدن فقط). لا يتم عرض مكان إلا إذا تم تضمين نوعه الأساسي في هذه القائمة. ويمكن تحديد ما يصل إلى 5 قيم. وإذا لم يتم تحديد أي أنواع، سيتم عرض جميع أنواع الأماكن.

includedRegionCodes[]

string

اختياريّ. يمكنك تضمين النتائج في المناطق المحدّدة فقط، والمحدّدة على أنّها رموز مناطق مؤلفة من حرفَين ومؤلفة من حرفَين كحد أقصى. لن تؤدي المجموعة الفارغة إلى تقييد النتائج. إذا تم ضبط كل من 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

اختياريّ. إذا كانت القيمة هي true، ستتضمّن الإجابة كلاً من توقّعات المكان والاستعلام. وبخلاف ذلك، لن تعرض الاستجابة سوى تنبؤات المكان.

sessionToken

string

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

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

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

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

نص الاستجابة

نموذج استجابة لـ places.الإكمال التلقائي.

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

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

object (Suggestion)

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

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

هذه القيم هي إزاحة أحرف يونيكود للرمز text. يمكن ضمان ترتيب النطاقات بقيم إزاحة متزايدة.

StringRange

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

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

integer

إزاحة قائمة على الصفر لأول حرف يونيكود من السلسلة (شاملة).

endOffset

integer

إزاحة قائمة على الصفر لآخر حرف يونيكود (غير شامل).

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 أو العكس.