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

خدمة الإكمال التلقائي (الجديدة) هي خدمة ويب تعرض مكان التنبؤات وتوقعات الاستعلام استجابةً لطلب 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

  لا يمكن أن يحتوي المكان إلا على نوع أساسي واحد من الأنواع المذكورة في. Table A أو الجدول ب. على سبيل المثال: قد يكون النوع الأساسي "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 متطابقة مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (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
      }
    }
  ]
}

جرّب الآن

يتيح لك "مستكشف واجهات برمجة التطبيقات" تقديم طلبات نموذجية حتى تتمكن من الإلمام بخيارات واجهة برمجة التطبيقات وواجهة برمجة التطبيقات.

1. انقر على رمز واجهة برمجة التطبيقات، ، على الجانب الأيمن من الصفحة.
2. يمكنك بشكل اختياري توسيع عرض المَعلمات العادية وضبط المَعلمة fields إلى قناع الحقل.
3. يمكنك تعديل نص الطلب اختياريًا.
4. انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.

5. في لوحة "مستكشف واجهة برمجة التطبيقات"، حدد رمز التوسيع، ، لتوسيع نافذة مستكشف واجهة برمجة التطبيقات