إكمال تلقائي (جديد)

خدمة الإكمال التلقائي (جديد) هي خدمة ويب تعرض تنبؤات عن الأماكن وتوقعات طلبات البحث استجابةً لطلب HTTP. في الطلب، حدد سلسلة بحث نصية وحدود جغرافية تتحكم في منطقة البحث.

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

يمكن أن يحتوي الرد من واجهة برمجة التطبيقات Autocomplete (New) على نوعين من التوقعات:

• توقّعات الأماكن: الأماكن، مثل الأنشطة التجارية والعناوين ونقاط الاهتمام، استنادًا إلى سلسلة نص الإدخال ومنطقة البحث المحدّدة يتم عرض توقعات الأماكن تلقائيًا.
• عبارات البحث المقترحة: سلاسل طلبات البحث التي تتطابق مع سلسلة نص الإدخال ومنطقة البحث. لا يتم عرض توقعات طلبات البحث بشكل تلقائي. استخدِم معلَمة طلب includeQueryPredictions لإضافة عبارات بحث مقترحة إلى الردّ.

على سبيل المثال، يمكنك استدعاء واجهة برمجة التطبيقات عن طريق إدخال سلسلة تحتوي على إدخال جزئي للمستخدم، "Sicilian piz"، مع حصر منطقة البحث على San Francisco, CA. يحتوي الرد بعد ذلك على قائمة باقتراحات الأماكن التي تتطابق مع سلسلة البحث ومنطقة البحث، مثل المطعم المسمى "مطبخ بيتزا صقلية"، إلى جانب تفاصيل حول المكان.

صُممت توقّعات الأماكن المعروضة لعرضها للمستخدم لمساعدته في اختيار المكان المطلوب. يمكنك إنشاء طلب تفاصيل المكان (جديد) للحصول على مزيد من المعلومات حول أي من توقّعات المكان التي تم إرجاعها.

يمكن أن يحتوي الرد أيضًا على قائمة عبارات البحث المقترحة التي تتطابق مع سلسلة البحث ومنطقة البحث، مثل "البيتزا والمعكرونة الصقلية". ويشمل كل توقّع بحث في الرد الحقل 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

تقديم طلب باستخدام الإكمال التلقائي (جديد)

تتوافق واجهة Places API مع واجهات برمجة التطبيقات الحالية الإكمال التلقائي والإكمال التلقائي لطلب البحث. إذا كنت على دراية بواجهات برمجة التطبيقات هذه، يُجري إصدار معاينة الإكمال التلقائي (الجديد) التغييرات التالية:

• تستخدم ميزة الإكمال التلقائي الجديدة طلبات HTTP POST. تمرير المعلَمات في نص الطلب أو في العناوين كجزء من طلب HTTP POST وفي المقابل، مع واجهات برمجة التطبيقات الحالية، يمكنك تمرير معلَمات عناوين URL باستخدام طلب HTTP GET.
• تتيح ميزة "الإكمال التلقائي" الجديدة استخدام كلّ من مفاتيح واجهة برمجة التطبيقات والرموز المميّزة OAuth كآلية للمصادقة.
• يمكن استخدام JSON فقط كتنسيق للاستجابة في ميزة الإكمال التلقائي الجديدة.

يسرد الجدول التالي المعلمات في واجهات برمجة التطبيقات الخاصة بالإكمال التلقائي والإكمال التلقائي لطلبات البحث الحالية التي تمت إعادة تسميتها أو تعديلها لميزة الإكمال التلقائي الجديدة، أو المعلمات التي لم تعد متوافقة.

المَعلمة الحالية	معلَمة جديدة	Notes
components	includedRegionCodes
language	languageCode
location	locationBias
ipbias		إذا حذفت كلاً من locationBias وlocationRestriction، ستستخدم واجهة برمجة التطبيقات انحياز عنوان IP تلقائيًا.
offset	inputOffset
radius	‫locationBias أو locationRestriction
region	regionCode
stricbounds	locationRestriction
sessiontoken	sessionToken
types	includedPrimaryTypes

حدود الاستخدام

أثناء إصدار المعاينة، تكون مقيدًا بإجراء 600 طلب بحث كحد أقصى في الدقيقة لكل مشروع.

خيارات الدعم في إصدارات المعاينة

على الرغم من أنّ "Google" ليست ملزَمة بتوفير الدعم لإصدارات المعاينة أو الميزات أو الوظائف في "الخدمات"، سننظر في الطلبات خلال مراحل التطوير هذه على أساس كل حالة على حدة.

• لا تغطي اتفاقية مستوى الخدمة في "منصة خرائط Google" إصدارات الإصدارات التجريبية.
• ويُنصح باستخدام آليات احتياطية، خاصةً إذا كنت تستخدم إصدارًا تجريبيًا في بيئة إنتاج. ومن الأمثلة على الحالات الاحتياطية: تم تجاوز الحصة المحدّدة، أو رموز استجابة ووقت استجابة غير متوقّعة، أو ردود غير متوقّعة عند مقارنتها بميزة الإكمال التلقائي الحالية.

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

• الإبلاغ عن خطأ
• تقديم طلب ميزة

إذا كان لديك أي سؤال آخر عن الميزات، يُرجى إرسال رسالة إلكترونية إلى newplaceapi@google.com.

لمحة عن الردّ

تعرض ميزة الإكمال التلقائي (جديد) كائن 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.

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

  يتم رفض الطلب مع ظهور خطأ INVALID_REQUEST في الحالات التالية:

  • تم تحديد أكثر من خمسة أنواع.
  • يتم تحديد أي أنواع غير معروفة.

• 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. وإذا لم يكُن الاسم متوفرًا باللغة المفضّلة، ستستخدم واجهة برمجة التطبيقات أقرب تطابق.

• 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

  تمثّل هذه السمة رمز المنطقة المستخدَم لتنسيق الاستجابة، ويتم تحديده على أنّه ccTLD ("نطاق المستوى الأعلى") الذي يتضمّن قيمة مؤلفة من حرفين. تتطابق معظم رموز ccTLD مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو "uk" (.co.uk)، في حين أنّ رمز ISO 3166-1 هو "gb" (من الناحية الفنية لكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").

  وإذا حدّدت رمز منطقة غير صالح، ستعرض واجهة برمجة التطبيقات خطأ INVALID_ARGUMENT. يمكن أن تؤثر المَعلمة في النتائج استنادًا إلى القانون الساري.

• sessionToken

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

أمثلة على الإكمال التلقائي (ميزة جديدة)

استخدام locationRestriction وlocationBias

تستخدم واجهة برمجة التطبيقات انحياز عنوان 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"
        ]
      }
    },
    ...
  ]
}

استخدام includePrimaryTypes

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

في المثال التالي، يمكنك تحديد سلسلة 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
      }
    }
  ]
}