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

مقدمة

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

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

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

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

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

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

يمكن أن يتضمّن الردّ أيضًا قائمة بتوقّعات طلب البحث التي تتطابق مع سلسلة البحث ومنطقة البحث، مثل "بيتزا ومعكرونة صقلية". يتضمّن كل توقع لطلب البحث في الرد الحقل 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 على معلومات تفصيلية حول نتيجة واحدة من نتائج التوقّع الخاصة بالأماكن، بما في ذلك معرّف المكان والوصف النصي.
  • لتحقيق تطابق أكبر مع إدخال المستخدم كما هو موضّح في المَعلمة input، قد يتضمّن الوصف النصي لتوقّع خاص بمكان أسماء بديلة للأماكن والشوارع ومكوّنات أخرى من العنوان. قد تختلف هذه الأسماء البديلة عن الأسماء التي يتم عرضها في الحقلَين displayName والعنوان ضمن نتائج تفاصيل المكان التي تتضمّن رقم تعريف المكان نفسه.
  • في هذا السياق، قد تكون الأسماء البديلة لبعض الأماكن بلغة مختلفة عن اللغة المتوقّعة استنادًا إلى المَعلمة languageCode، وذلك حسب الأسماء التي تتطابق مع بيانات أدخلها المستخدم بشكل أكبر.
• يحتوي حقل 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
            }]
        },
        ...
    }
  ...]
}

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

• input

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

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

• 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: *

• includeFutureOpeningBusinesses

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

• 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، بما في ذلك الأسماء بلغات أخرى غير اللغة المحدّدة في المَعلمة 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 ("نطاق المستوى الأعلى"). معظم رموز نطاقات المستوى الأعلى لرمز البلد تتطابق مع رموز ISO 3166-1، مع بعض الاستثناءات البارزة. على سبيل المثال، نطاق المستوى الأعلى لرمز البلد في المملكة المتحدة هو "uk" (.co.uk)، بينما رمز ISO 3166-1 الخاص بها هو "gb" (وهو يشير تقنيًا إلى كيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").

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

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

• sessionToken

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

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

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

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

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

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
      }
    }
  ]
}

البحث عن الأنشطة التجارية التي ستفتح في المستقبل

يعرض المثال التالي طلبًا بشأن ميزة "الإكمال التلقائي (جديد)" للأنشطة التجارية التي ستفتح في المستقبل في نيو ميدوز، أيداهو:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

تتضمّن الاستجابة تفاصيل حول المكان، ولكنّها لا تتضمّن تاريخ الافتتاح.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

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

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

حصر الوصول إلى الموقع الجغرافي

يمكنك حصر النتائج على منطقة محدّدة من خلال تمرير المَعلمة locationRestriction.

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

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

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

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

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

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

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