الترميز الجغرافي بدقة محسّنة

المطوّرون في المنطقة الاقتصادية الأوروبية

تتيح الطريقتان GeocodeAddress وSearchDestinations استخدام مَعلمة effort اختيارية تتيح لك التحكّم في المفاضلة بين وقت استجابة الردّ ودقة تحليل العنوان.

في حين أنّ الترميز الجغرافي العادي يعالج العناوين البريدية المنسَّقة بشكل جيد في أقل من ثانية، غالبًا ما تكون المدخلات الواقعية غير مكتملة أو غير رسمية أو معقدة (على سبيل المثال، "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai" أو "where the warriors play, sf"). من خلال ضبط مستوى effort أعلى، يمكنك توجيه Geocoding API لتطبيق الاستدلال الموسّع وإزالة الغموض لحل العناوين الصعبة.

مستويات الجهد

حدِّد إحدى القيم التالية للمَعلمة effort:

مستوى الجهد الوصف وقت الاستجابة المعتاد حالات الاستخدام المقترَحة
EFFORT_UNSPECIFIED القيمة التلقائية يعمل بالطريقة نفسها التي يعمل بها جهد LOW. أقل من ثانية الترميز الجغرافي العادي التلقائي
LOW يتم تحسينه لتقديم أسرع أوقات استجابة. لا يتم إجراء بحث موسّع أو توضيح للعناوين الصعبة. أقل من ثانية البحث التفاعلي في الوقت الفعلي، والتحقّق من العناوين العادية بكميات كبيرة
MEDIUM يوازن بين السرعة والدقة. تتم الاستجابة لمعظم الطلبات بوقت استجابة عادي وسريع. بالنسبة إلى العناوين الغامضة أو الصعبة، تطبّق الخدمة معالجة إضافية لتحسين الدقة، وقد يستغرق ذلك بضع ثوانٍ. أقل من ثانية للعناوين العادية، وما يصل إلى بضع ثوانٍ (أقل من أو يساوي 4 ثوانٍ) للعناوين الغامضة سير عمل المستخدم التفاعلي (مثل تأكيد العنوان عند الدفع) حيث يمكن للمستخدمين تحمّل توقّف مؤقت قصير
HIGH يؤدي ذلك إلى زيادة دقة تحليل العناوين غير المكتملة أو غير الرسمية أو المعقّدة إلى أقصى حد. قد يستغرق الردّ وقتًا أطول بكثير. ما يصل إلى 20 ثانية للعناوين المعقّدة المعالجة في الخلفية أو الترميز الجغرافي المجمّع أو إرسال الخدمات اللوجستية أو تحسين العناوين غير المتزامن بعد الدفع

أمثلة على الطلبات

البحث عن الوجهات (SearchDestinations)

يُرجى تضمين الحقل effort في نص طلب JSON لطلب POST إلى https://geocode.googleapis.com/v4alpha/geocode/destinations. تؤثر المَعلمة effort بشكل أساسي في دقة addressQuery:

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai"
  },
  "effort": "HIGH"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

الترميز الجغرافي لعنوان (GeocodeAddress)

مرِّر مَعلمة effort كمَعلمة طلب بحث لعنوان URL في طلب GET إلى نقطة النهاية /v4alpha/:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4alpha/geocode/address/where+the+warriors+play,+sf?effort=MEDIUM"

الحدّ من تأثير وقت الاستجابة

عند استخدام جهد MEDIUM أو HIGH في تطبيقك، يكون إرسال طلب أحادي المسار هو أبسط عملية تكامل، ولكن الطلبات في هذه الأوضاع يمكن أن تؤدي إلى زيادة وقت الاستجابة، ما قد يؤخر سير العمل المتزامن والموجّه للمستخدمين والحساس لوقت الاستجابة.

للحدّ من تأثير وقت الاستجابة هذا في مسارات المستخدمين التفاعلية (مثل الدفع أو الحجز)، يمكنك استخدام سير عمل متعدّد المسارات:

  1. الخطوة 1 (تفاعلية): أرسِل طلبًا متزامنًا باستخدام effort=LOW (أو الإعداد التلقائي) للتحقّق من صحة العنوان على الفور مع وقت استجابة أقل من ثانية.
  2. الخطوة 2 (في الخلفية): أرسِل طلب متابعة غير متزامن باستخدام effort=MEDIUM أو effort=HIGH (على سبيل المثال، بعد الدفع أو قبل الإرسال) لتحويل العناوين المعقّدة إلى إحداثيات ومداخل ونقاط تنقّل عالية الدقة بدون حظر المستخدم.

سقف الاستخدام

خلال مرحلة الإطلاق التجريبي (v4alpha)، تخضع الطلبات التي تم ضبط effort فيها على MEDIUM أو HIGH لحدود معدّل أكثر صرامة من الطلبات العادية (LOW). إذا تجاوز تطبيقك هذه الحدود القصوى، ستعرض واجهة برمجة التطبيقات الخطأ RESOURCE_EXHAUSTED (HTTP 429). إذا واجهت أخطاء HTTP 429 أو كنت بحاجة إلى حصة أعلى لحالة الاستخدام، يُرجى التواصل معنا من خلال قناة الملاحظات.

الملاحظات

هذه ميزة تجريبية في Geocoding API. يُرجى إرسال ملاحظاتك إلى geocoding-feedback-channel@google.com.