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

مقدمة

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

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

يمكن أن تتضمّن الاستجابة من ميزة "الإكمال التلقائي (الجديدة)" نوعَين من عبارات البحث المقترَحة:

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

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

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

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

المعلمات المطلوبة

• إدخال

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

المعلمات الاختيارية

• FieldMask

  حدِّد قائمة الحقول التي سيتم عرضها في الاستجابة من خلال إنشاء قناع حقل الاستجابة. مرِّر قناع حقل الاستجابة إلى الطريقة باستخدام عنوان HTTP X-Goog-FieldMask.

  حدِّد قائمة مفصولة بفواصل لحقول الاقتراحات المطلوب عرضها. على سبيل المثال، لاسترداد suggestions.placePrediction.text.text وsuggestions.queryPrediction.text.text من الاقتراح.

    X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

  استخدِم * لاسترداد جميع الحقول.

    X-Goog-FieldMask: *

• includedPrimaryTypes

  يمكن أن يكون للمكان نوع أساسي واحد فقط من الأنواع المدرَجة في الجدول أ أو الجدول ب. على سبيل المثال، قد يكون النوع الأساسي "mexican_restaurant" أو "steak_house".

  تعرض واجهة برمجة التطبيقات تلقائيًا جميع الأماكن استنادًا إلى المَعلمة input، بغض النظر عن قيمة النوع الأساسي المرتبطة بالمكان. يمكنك حصر النتائج على نوع أساسي معيّن أو أنواع أساسية معيّنة من خلال تمرير المَعلمة includedPrimaryTypes.

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

  قد تتضمّن هذه المَعلمة أيضًا، بدلاً من ذلك، إحدى القيمتين (regions) أو (cities). تفلتر مجموعة النوع (regions) المناطق أو الأقسام، مثل الأحياء والرموز البريدية. تتضمّن مجموعة النوع (cities) فلاتر للأماكن التي تحدّدها Google كمدينة.

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

  • تم تحديد أكثر من خمسة أنواع.
  • يتم تحديد أي نوع بالإضافة إلى (cities) أو (regions).
  • يتم تحديد أي أنواع غير معروفة.

• includePureServiceAreaBusinesses

  إذا تم ضبطها على true، سيتضمّن الرد الأنشطة التجارية التي تقدّم خدماتها من خلال زيارة العملاء أو التوصيل المباشر، ولكن ليس لديها موقع جغرافي ثابت. إذا تم ضبطها على false، تعرض واجهة برمجة التطبيقات الأنشطة التجارية التي لها موقع جغرافي فقط.

• includeQueryPredictions

  إذا كانت القيمة true، تتضمّن الاستجابة عبارات البحث المقترَحة والأماكن المقترَحة. القيمة التلقائية هي false، ما يعني أنّ الرد يتضمّن توقعات حول الأماكن فقط.

• includedRegionCodes

  لا تضمِّن سوى النتائج من قائمة المناطق المحدّدة، والتي يتم تحديدها كمصفوفة تتضمّن ما يصل إلى 15 قيمة لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) مؤلّفة من حرفين. في حال عدم تضمينها، لن يتم تطبيق أي قيود على الرد. على سبيل المثال، لتحديد المناطق بألمانيا وفرنسا:

      "includedRegionCodes": ["de", "fr"]

  إذا حدّدت كلاً من locationRestriction وincludedRegionCodes، ستظهر النتائج في المنطقة المشتركة بين الإعدادَين.

• inputOffset

  إزاحة حرف Unicode المستندة إلى الصفر والتي تشير إلى موضع المؤشر في 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

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

  تكون الاقتراحات متحيزة أيضًا استنادًا إلى رموز المناطق. تنصح Google بضبط regionCode وفقًا للإعدادات المفضّلة للمستخدم على مستوى المنطقة.

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

• sessionToken

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

اختيار المَعلمات التي ستؤثّر في النتائج

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

حصر البحث على منطقة معيّنة باستخدام locationRestriction

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

curl -X POST -d '{
  "input": "Art museum",
  "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/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

يمكنك أيضًا استخدام locationRestriction لحصر عمليات البحث على إطار عرض مستطيل. يقتصر المثال التالي على وسط مدينة سان فرانسيسكو:

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

يتم تضمين النتائج في مصفوفة suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

تحديد نطاق البحث بمنطقة معيّنة باستخدام 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

تتضمّن النتائج الآن المزيد من العناصر، بما في ذلك النتائج خارج نطاق نصف القطر البالغ 5, 000 متر:

{
  "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"
        ]
      }
    },
    ...
  ]
}

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

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -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": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "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": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

استخدام includedPrimaryTypes

استخدِم المَعلمة 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
      }
    }
  ]
}

المسافة غير متوفّرة في الردّ

في بعض الحالات، لا يتضمّن نص الردّ distanceMeters، حتى عندما يكون origin مضمّنًا في الطلب. قد يحدث ذلك في الحالات التالية:

• لا يتم تضمين distanceMeters في توقعات route.
• لا يتم تضمين distanceMeters عندما تكون قيمته 0، وهو ما يحدث بالنسبة إلى التوقعات التي تبعد أقل من متر واحد عن الموقع الجغرافي origin المقدَّم.

ستعرض مكتبات البرامج التي تحاول قراءة الحقل distanceMeters من عنصر تم تحليله حقلاً بالقيمة 0. لتجنُّب تضليل المستخدمين، لا تعرض مسافة صفرية للمستخدمين.

تحسين ميزة "الإكمال التلقائي" (جديد)

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

في ما يلي بعض الإرشادات العامة:

• أسرع طريقة لتطوير واجهة مستخدم تعمل هي استخدام الأداة "الإكمال التلقائي (جديد)" في Maps JavaScript API، أو الأداة "الإكمال التلقائي (جديد)" في Places SDK لنظام التشغيل Android، أو الأداة "الإكمال التلقائي (جديد)" في Places SDK لنظام التشغيل iOS.
• التعرّف على حقول البيانات الأساسية لخاصية "الإكمال التلقائي" (جديد) من البداية
• حقلَي "تفضيل الموقع الجغرافي" و"حظر الموقع الجغرافي" اختياريان، ولكن يمكن أن يكون لهما تأثير كبير في أداء ميزة "الإكمال التلقائي".
• استخدِم ميزة معالجة الأخطاء للتأكّد من أنّ تطبيقك يتراجع بشكل سليم في حال عرض واجهة برمجة التطبيقات رسالة خطأ.
• تأكَّد من أنّ تطبيقك يتعامل مع الحالات التي لا يتم فيها تحديد أي خيار، وأنّه يوفّر للمستخدمين طريقة لمواصلة الاستخدام.

أفضل الممارسات لتحسين التكلفة

تحسين التكلفة الأساسية

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

تحسين التكلفة بشكلٍ متقدّم

ننصحك بتنفيذ ميزة "الإكمال التلقائي (جديدة)" آليًا للوصول إلى رمز التخزين التعريفي: أسعار طلبات الإكمال التلقائي وطلب نتائج Geocoding API حول المكان المحدّد بدلاً من "تفاصيل المكان (جديدة)". يكون التسعير لكل طلب مقترنًا بواجهة برمجة التطبيقات Geocoding API أكثر فعالية من حيث التكلفة من التسعير لكل جلسة (استنادًا إلى الجلسة) في حال استيفاء الشرطَين التاليَين:

• إذا كنت تحتاج فقط إلى خطوط الطول والعرض أو عنوان المكان الذي اختاره المستخدم، تقدّم Geocoding API هذه المعلومات بتكلفة أقل من طلب Place Details (New).
• إذا اختار المستخدمون نتيجة بحث مقترَحة من ميزة "الإكمال التلقائي" في غضون أربعة طلبات أو أقل من ميزة "الإكمال التلقائي (جديد)"، قد يكون التسعير لكل طلب أكثر فعالية من حيث التكلفة من التسعير لكل جلسة.

هل يتطلّب تطبيقك أي معلومات أخرى غير العنوان وخط العرض/خط الطول الخاص بالتوقّع المحدّد؟

أفضل الممارسات المتعلّقة بالأداء

توضّح الإرشادات التالية طرقًا لتحسين أداء ميزة "الإكمال التلقائي (جديد)":

• أضِف قيود البلدان وتحسين الموقع الجغرافي وخيار اللغة المفضّلة (في عمليات التنفيذ الآلية) إلى عملية تنفيذ ميزة "الإكمال التلقائي (جديد)". لا حاجة إلى تحديد اللغة المفضّلة عند استخدام الأدوات المصغّرة لأنّها تستند إلى اللغة المفضّلة المحدّدة في متصفّح المستخدم أو جهازه الجوّال.
• إذا كانت ميزة "الإكمال التلقائي (جديدة)" مصحوبة بخريطة، يمكنك تحديد الموقع الجغرافي حسب إطار عرض الخريطة.
• في الحالات التي لا يختار فيها المستخدم إحدى عبارات البحث المقترَحة من ميزة "الإكمال التلقائي (جديد)"، وذلك عادةً لأنّ أيًا من عبارات البحث المقترَحة هذه ليس عنوان النتيجة المطلوب، يمكنك إعادة استخدام إدخال المستخدم الأصلي لمحاولة الحصول على نتائج أكثر صلة:
  • إذا كنت تتوقّع أن يدخل المستخدم معلومات العنوان فقط، أعِد استخدام إدخال المستخدم الأصلي في طلب إلى Geocoding API.
  • إذا كنت تتوقّع أن يُدخل المستخدم طلبات بحث عن مكان معيّن حسب الاسم أو العنوان، استخدِم طلب "تفاصيل المكان (جديد)". إذا كنت تتوقّع ظهور النتائج في منطقة معيّنة فقط، استخدِم تحسين النتائج حسب الموقع الجغرافي.
  تشمل السيناريوهات الأخرى التي يُنصح فيها بالرجوع إلى Geocoding API ما يلي:
  • المستخدمون الذين يدخلون عناوين أماكن فرعية، مثل عناوين وحدات أو شقق معيّنة داخل مبنى على سبيل المثال، يؤدي إدخال العنوان التشيكي "Stroupežnického 3191/17, Praha" إلى ظهور عبارة بحث مقترَحة جزئية في ميزة "الإكمال التلقائي (الجديدة)".
  • المستخدمون الذين يدخلون عناوين تتضمّن بادئات مقاطع طرق، مثل "23-30 29th St, Queens" في مدينة نيويورك أو "47-380 Kamehameha Hwy, Kaneohe" في جزيرة كاواي في هاواي

تفضيل المواقع الجغرافية

يمكنك توجيه النتائج إلى منطقة محدّدة من خلال تمرير المَعلمة location والمَعلمة radius. يوجّه هذا الخيار ميزة "الإكمال التلقائي (جديد)" إلى تفضيل عرض النتائج ضمن المنطقة المحدّدة. قد يستمر عرض النتائج خارج المنطقة المحدّدة. يمكنك استخدام المَعلمة components لفلترة النتائج وعرض الأماكن الواقعة ضمن بلد محدّد فقط.

تقييد الموقع الجغرافي

لحصر النتائج في منطقة محدّدة، أضِف المَعلمة locationRestriction.

يمكنك أيضًا حصر النتائج بالمنطقة المحدّدة بواسطة location والمَعلمة radius، وذلك من خلال إضافة المَعلمة locationRestriction. يوجّه هذا الإعداد ميزة "الإكمال التلقائي (الجديدة)" لعرض نتائج فقط ضمن تلك المنطقة.

جرِّبها الآن.

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

1. انقر على رمز واجهة برمجة التطبيقات api في يسار الصفحة.

2. عدِّل مَعلمات الطلب اختياريًا.

3. انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.

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