Package google.maps.addressvalidation.v1

الفهرس

AddressValidation

الخدمة للتحقّق من صحة العناوين

ProvideValidationFeedback

rpc ProvideValidationFeedback(ProvideValidationFeedbackRequest) returns (ProvideValidationFeedbackResponse)

تشير هذه السمة إلى ملاحظات حول نتيجة تسلسل محاولات التحقّق. يجب أن يكون هذا هو آخر إجراء يتم إجراؤه بعد سلسلة من إجراءات التحقّق من العنوان نفسه، ويجب تنفيذه بعد إتمام المعاملة. يجب إرسال هذا الطلب مرة واحدة فقط لتسلسل ValidateAddress طلب مطلوب للتحقّق من صحة العنوان بالكامل.
ValidateAddress

rpc ValidateAddress(ValidateAddressRequest) returns (ValidateAddressResponse)

للتحقّق من صحة عنوان

العنوان

تفاصيل العنوان بعد معالجته تشمل مرحلة ما بعد المعالجة تصحيح الأجزاء التي تحتوي على أخطاء إملائية في العنوان واستبدال الأجزاء غير الصحيحة واستنتاج الأجزاء المفقودة.

الحقول
formatted_address

string

العنوان الذي تمّت معالجته، وهو بتنسيق عنوان سطر واحد وفقًا لقواعد تنسيق العناوين في المنطقة التي يقع فيها العنوان

ملاحظة: قد لا يتطابق تنسيق هذا العنوان مع تنسيق العنوان في الحقل postal_address. على سبيل المثال، يمثّل الرمز postal_address دائمًا البلد على شكل region_code مكوّن من حرفَين، مثل "US" أو "NZ". في المقابل، يستخدم هذا الحقل صيغة أطول لاسم البلد، مثل "USA" أو "نيوزيلندا".
postal_address

PostalAddress

تمثّل هذه السمة العنوان الذي تمّت معالجته بعد اكتماله كعنوان بريدي.
address_components[]

AddressComponent

قائمة بدون ترتيب مكونات العنوان الفردية للعنوان المنسَّق والمصحَّح، بالإضافة إلى معلومات التحقّق من الصحة يوفر هذا معلومات عن حالة التحقق من المكونات الفردية.

لا يتم ترتيب مكوّنات العنوان بطريقة معيّنة. لا تفترض أي ترتيب لعناصر العنوان في القائمة.
missing_component_types[]

string

أنواع المكوّنات التي كان من المتوقّع أن تكون متوفّرة في عنوان بريدي منسّق بشكل صحيح ولكن لم يتم العثور عليها في الإدخال ولم يكن من الممكن استنتاجها. لا تتوفّر مكوّنات من هذا النوع في formatted_address أو postal_address أو address_components. على سبيل المثال، ['street_number', 'route'] لإدخال مثل "Boulder, Colorado, 80301, USA". يمكن العثور على قائمة الأنواع المحتملة هنا.
unconfirmed_component_types[]

string

تمثّل هذه السمة أنواع المكوّنات المتوفّرة في address_components ولكن تعذّر التأكّد من صحتها. يتم توفير هذا الحقل لتسهيل الاستخدام: إنّ محتوياته مكافئة للتنقّل في address_components للعثور على أنواع جميع المكوّنات التي لا يكون فيها confirmation_level هو CONFIRMED أو لم يتم ضبط علامة inferred على true. يمكنك الاطّلاع على قائمة الأنواع المحتمَلة هنا.
unresolved_tokens[]

string

يشير هذا المصطلح إلى أي رموز مميّزة في الإدخال لم نتمكّن من حلّها. قد يكون هذا إدخالًا لم يتم التعرّف عليه كجزء صالح من عنوان. على سبيل المثال، بالنسبة إلى إدخال مثل "Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US"، قد تبدو الرموز غير المحسَّنة على النحو التالي: ["Parcel", "0000123123", "&", "0000456456"].

AddressComponent

يمثّل مكوّن عنوان، مثل شارع أو مدينة أو ولاية.

الحقول
component_name

ComponentName

اسم هذا المكوّن.
component_type

string

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

ConfirmationLevel

يشير إلى مستوى اليقين الذي لدينا من صحة المكون.
inferred

bool

يشير ذلك إلى أنّ المكوّن لم يكن جزءًا من الإدخال، ولكننا استنتجناه من موقع العنوان ونعتقد أنّه يجب تقديمه لعنوان كامل.
spell_corrected

bool

يشير إلى تصحيح خطأ إملائي في اسم المكوّن. لا تُبلغ واجهة برمجة التطبيقات دائمًا عن التغييرات من صيغة إملائية إلى أخرى، مثل تغيير "centre" إلى "center". ولا تشير الأداة أيضًا دائمًا إلى الأخطاء الإملائية الشائعة، مثل تغيير "Amphitheater Pkwy" إلى "Amphitheatre Pkwy".
replaced

bool

يشير ذلك إلى أنّه تم استبدال اسم المكوّن باسم مختلف تمامًا، على سبيل المثال، استبدال رمز بريدي غير صحيح برمز صحيح للعنوان. هذا ليس تغييرًا جماليًا، بل تم تغيير مكوّن الإدخال إلى مكوّن مختلف.
unexpected

bool

يشير إلى مكوّن عنوان غير متوقّع أن يكون متوفّرًا في عنوان بريدي للمنطقة المحدّدة. ولم نحتفظ به إلا لأنّه كان جزءًا من الإدخال.

ConfirmationLevel

القيم المختلفة المحتمَلة لمستويات التأكيد

عمليات التعداد
CONFIRMATION_LEVEL_UNSPECIFIED القيمة التلقائية هذه القيمة غير مستخدمة.
CONFIRMED لقد تمكّنا من التحقّق من توفّر هذا المكوّن ومن أنّه منطقي في سياق بقية العنوان.
UNCONFIRMED_BUT_PLAUSIBLE تعذّر تأكيد هذا العنصر، ولكن من المحتمل وجوده. على سبيل المثال، رقم شارع ضمن نطاق صالح معروف من الأرقام في شارع لا تُعرَف فيه أرقام منازل معيّنة.
UNCONFIRMED_AND_SUSPICIOUS لم يتم تأكيد هذا المكوّن ومن المرجّح أن يكون غير صحيح. على سبيل المثال، حي لا يناسب بقية العنوان

AddressMetadata

البيانات الوصفية للعنوان. لا يمكن ضمان تعبئة الحقل metadata بالكامل لكل عنوان يتم إرساله إلى Address Validation API.

الحقول
business

bool

يشير إلى أن هذا هو عنوان نشاط تجاري. إذا لم يتم ضبط القيمة، يشير ذلك إلى أنّها غير معروفة.
po_box

bool

يشير إلى عنوان صندوق البريد. إذا لم يتم ضبط القيمة، يشير ذلك إلى أنّها غير معروفة.
residential

bool

يشير إلى أن هذا هو عنوان الإقامة. في حال ترك هذه السياسة بدون ضبط، يعني ذلك أنّ القيمة غير معروفة.

ComponentName

عنصر ملفوف لاسم المكوّن

الحقول
text

string

نص الاسم. على سبيل المثال، "الشارع الخامس" لاسم شارع أو "1253" لرقم شارع.
language_code

string

تمثّل هذه السمة رمز اللغة BCP-47. لن يظهر هذا الحقل إذا لم يكن اسم المكوّن مرتبطًا بلغة، مثل رقم شارع.

الترميز الجغرافي

يحتوي على معلومات عن المكان الذي تمّ ترميزه جغرافيًا.

الحقول
location

LatLng

الموقع الجغرافي المشفَّر جغرافيًا للبيانات المُدخلة.

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

PlusCode

رمز Plus Codes المقابل للموقع الجغرافي location
bounds

Viewport

حدود المكان الذي تم ترميزه جغرافيًا
feature_size_meters

float

حجم المكان الذي تم ترميزه جغرافيًا، بالمتر وهذا مقياس آخر لحدة الموقع الجغرافي المرمَّز جغرافيًا، ولكن من حيث الحجم الفعلي بدلاً من المعنى الدلالي.
place_id

string

رقم تعريف المكان للمكان الذي يتم فيه ترميز هذا الإدخال الجغرافي.

لمزيد من المعلومات عن أرقام تعريف الأماكن، يُرجى الاطّلاع على هذا الرابط.
place_types[]

string

أنواع الأماكن التي تم ترميزها جغرافيًا باستخدام الإدخال مثلاً: ['locality', 'political'] يمكنك الاطّلاع على القائمة الكاملة للأنواع هنا.

LanguageOptions

الإصدار التجريبي: تتوفّر هذه الميزة في إصدار تجريبي (قبل طرحها للجميع). قد يتوفّر دعم محدود للمنتجات والميزات المتوفّرة في مرحلة ما قبل التوفّر للجمهور العام، وقد لا تتوافق التغييرات في المنتجات والميزات المتوفّرة في مرحلة ما قبل التوفّر للجمهور العام مع الإصدارات الأخرى المتاحة في مرحلة ما قبل التوفّر للجمهور العام. تخضع "عروض مرحلة ما قبل الإطلاق" للبنود المحدّدة لخدمة Google Maps Platform. لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق.

لتفعيل واجهة برمجة تطبيقات التحقق من صحة العنوان الجغرافي لتضمين معلومات إضافية في الرد.

الحقول
return_english_latin_address

bool

المعاينة: عرض google.maps.addressvalidation.v1.Address باللغة الإنجليزية لمزيد من التفاصيل، انتقِل إلى google.maps.addressvalidation.v1.ValidationResult.english_latin_address.

PlusCode

رمز Plus Codes (http://plus.codes) هو مرجع موقع جغرافي يتضمّن تنسيقَين: رمز عالمي يحدّد مستطيلاً أصغر أو أكبر بقياس 14 مترًا في 14 مترًا (1/8000 من الدرجة)، ورمز مركب يستبدل البادئة بموقع جغرافي مرجعي.

الحقول
global_code

string

الرمز العالمي (الكامل) للمكان، مثل "9FWM33GV+HQ"، الذي يمثل مساحة 1/8000 في 1/8000 درجة (14 × 14 متر تقريبًا).
compound_code

string

الرمز المركّب للمكان، مثل "33GV+HQ, Ramberg, Norway"، الذي يحتوي على لاحقة الرمز العام ويستبدل البادئة باسم منسق للكيان المرجعي.

ProvideValidationFeedbackRequest

طلب إرسال ملاحظات حول عملية التحقّق

الحقول
conclusion

ValidationConclusion

مطلوب. نتيجة تسلسل محاولات التحقّق.

إذا تم ضبط هذا الحقل على VALIDATION_CONCLUSION_UNSPECIFIED، سيتم عرض خطأ INVALID_ARGUMENT.
response_id

string

مطلوب. تمثّل هذه السمة رقم تعريف الردّ المخصّص لهذه الملاحظات. يجب أن يكون هذا العنصر هو [response_id][google.maps.addressvalidation.v1.ValidateAddressRequest.response_id] من أول استجابة في سلسلة من محاولات التحقّق من العنوان.

ValidationConclusion

النتائج النهائية المحتمَلة لتسلسل طلبات التحقّق من العنوان اللازمة للتحقّق من عنوان

عمليات التعداد
VALIDATION_CONCLUSION_UNSPECIFIED هذه القيمة غير مستخدَمة. إذا تم ضبط الحقل ProvideValidationFeedbackRequest.conclusion على VALIDATION_CONCLUSION_UNSPECIFIED، سيتم عرض الخطأ INVALID_ARGUMENT.
VALIDATED_VERSION_USED تم استخدام نسخة العنوان التي تعرضها واجهة برمجة تطبيقات التحقق من صحة العنوان في المعاملة.
USER_VERSION_USED تم استخدام نسخة العنوان التي قدّمها المستخدم في المعاملة.
UNVALIDATED_VERSION_USED تم استخدام نسخة من العنوان تم إدخالها بعد محاولة التحقّق الأخيرة ولكن لم تتم إعادة التحقّق منها في المعاملة.
UNUSED تم إلغاء المعاملة ولم يتم استخدام العنوان.

ProvideValidationFeedbackResponse

لا يتضمّن هذا النوع أيّ حقول.

ردّ على ملاحظات التحقّق.

يكون الردّ فارغًا إذا تم إرسال الملاحظات بنجاح.

UspsAddress

تمثيل USPS لعنوان في الولايات المتحدة

الحقول
first_address_line

string

السطر الأول من العنوان
firm

string

اسم الشركة
second_address_line

string

سطر العنوان الثاني
urbanization

string

اسم منطقة حضرية في بورتوريكو.
city_state_zip_address_line

string

المدينة + الولاية + الرمز البريدي.
city

string

اسم المدينة.
state

string

رمز حالة مكوّن من حرفَين.
zip_code

string

الرمز البريدي، مثل 10009
zip_code_extension

string

إضافة الرمز البريدي المكوّن من 4 أرقام، مثل 5023

UspsData

بيانات USPS للعنوان لا يمكن ضمان تعبئة الحقل uspsData بالكامل لكل عنوان في الولايات المتحدة أو في بورتوريكو يتم إرساله إلى Address Validation API. ننصحك بدمج حقول العنوان الاحتياطي في الاستجابة إذا كنت تستخدِم uspsData كجزء أساسي من الاستجابة.

الحقول
standardized_address

UspsAddress

عنوان USPS الموحّد.
delivery_point_code

string

رمز نقطة التسليم المكوّن من رقمَين
delivery_point_check_digit

string

رقم التحقّق لنقطة التسليم تتم إضافة هذا الرقم إلى نهاية delivery_point_barcode للرسائل التي يتم مسحها ضوئيًا آليًا. من المفترض أن تؤدي إضافة جميع أرقام delivery_point_barcode وdelivery_point_check_digit وpostal_code وZIP+4 معًا إلى الحصول على رقم قابل للقسمة على 10.
dpv_confirmation

string

القيم المحتملة لتأكيد DPV لعرض حرف واحد أو عدم عرض أي قيمة.

  • N: تعذّر على فريق DPV تأكيد معلومات الرقم الأساسي وأي رقم ثانوي.
  • D: تم تأكيد عنوان DPV للرقم الأساسي فقط، وكانت معلومات الرقم الثانوي غير متوفّرة.
  • S: تم تأكيد عنوان DPV للرقم الأساسي فقط، وكانت معلومات الرقم الثانوي متوفّرة ولكن لم يتم تأكيدها.
  • Y: تم تأكيد صحة عنوان DPV للعنوان الأساسي وأي أرقام ثانوية.
  • فارغ: إذا لم يحتوي الردّ على قيمة dpv_confirmation، يعني ذلك أنّه لم يتم إرسال العنوان لتأكيد عملية الدفع عبر نقطة البيع.
dpv_footnote

string

الهوامش من عملية التحقّق من نقطة التسليم يمكن ربط عدة حواشي سفلية معًا في السلسلة نفسها.

  • AA: مطابقة العنوان الذي تم إدخاله مع ملف ZIP+4
  • A1: لم تتم مطابقة العنوان الذي أدخلته مع ملف ZIP+4
  • BB: مطابقة مع DPV (جميع المكوّنات)
  • CC: الرقم الثانوي غير مطابق وغير مطلوب
  • C1: عدم تطابق الرقم الثانوي مع الرقم المطلوب
  • N1: لا يتضمّن عنوان المبنى الشاهق رقمًا ثانويًا.
  • M1: عدم توفّر الرقم الأساسي
  • M3: الرقم الأساسي غير صالح
  • P1: عدم توفّر رقم صندوق البريد أو صندوق البريد السريع أو صندوق البريد الوارد في عنوان الإدخال
  • P3: رقم صندوق البريد أو رقم سجلّ الأرباح أو رقم صندوق البريد السريع غير صالح
  • F1: تطابق عنوان الإدخال مع عنوان عسكري
  • G1: عنوان الإدخال مطابق لعنوان تسليم عام
  • U1: عنوان إدخال مطابق لرمز بريدي فريد
  • PB: عنوان إدخال مطابق لسجلّ PBSA
  • RR: عنوان تم تأكيده من خلال عملية DPV يتضمّن معلومات PMB
  • R1: تم تأكيد عنوان DPV بدون معلومات PMB
  • R7: سجلّ مسار الناقل R777 أو R779
  • IA: تم تحديد العنوان الذي تم إبلاغه به
  • TA: الرقم الأساسي الذي تمت مطابقته عن طريق إزالة حرف أبجدي لاحق
dpv_cmra

string

يشير إلى ما إذا كان العنوان تابعًا لوكالة CMRA (وكالة استلام البريد التجاري)، وهي وكالة خاصة تتلقّى البريد للعملاء. تعرض حرفًا واحدًا.

  • Y: العنوان هو هيئة CMRA
  • N: العنوان ليس عنوان بريد إلكتروني مخصّصًا لتلقّي الرسائل القصيرة
dpv_vacant

string

هل هذا المكان خالٍ؟ لعرض حرف واحد.

  • Y: العنوان شاغر
  • N: العنوان غير شاغر
dpv_no_stat

string

هل هذا عنوان لا يتضمّن إحصاءات أم عنوان نشط؟ إنّ العناوين غير المُسجَّلة هي العناوين التي لا يتمّ استخدامها بشكلٍ مستمر أو العناوين التي لا تخدمها شركة USPS. لعرض حرف واحد.

  • Y: العنوان غير نشط
  • N: العنوان نشط
dpv_no_stat_reason_code

int32

يشير إلى نوع NoStat. لعرض رمز سبب كعدد صحيح.

  • 1: العناوين التي لا تتلقّى رسائل إلكترونية من خدمة USPS مباشرةً، ولكن يتم توصيلها إلى عنوان تسليم يوفّرها الخدمة.
  • 2: CDS: العناوين التي لم تصبح قابلة للتسليم بعد على سبيل المثال، تقسيم جديد تم تحديد قطع الأراضي والأرقام الأساسية فيه، ولكن لا يتوفّر أيّ هيكل بعد للاستخدام.
  • 3: تعارض: عناوين لا تؤكدها خدمة DPV
  • ‫4: CMZ (المناطق الجامعية والعسكرية والأنواع الأخرى) - سجلّات الرمز البريدي + 4 التي دمجتها USPS في البيانات
  • 5: عادي - يشير إلى العناوين التي لا تتلقّى خدمة التسليم ولا يتم احتساب العناوين ضمن عمليات التسليم الممكنة.
  • 6: مطلوب عنوان ثانوي: يتطلب العنوان معلومات ثانوية.
dpv_drop

string

تشير العلامة إلى أنّه يتم تسليم البريد إلى حاوية استقبال واحدة في موقع إلكتروني. لعرض حرف واحد.

  • Y: يتم تسليم البريد إلى علبة استقبال واحدة في موقع إلكتروني.
  • N: لا يتم تسليم البريد إلى صندوق استقبال واحد في الموقع.
dpv_throwback

string

يشير ذلك إلى أنّه لا يتم تسليم البريد إلى عنوان الشارع. لعرض حرف واحد.

  • Y: لا يتم تسليم البريد إلى عنوان الشارع.
  • N: يتم تسليم البريد إلى عنوان الشارع.
dpv_non_delivery_days

string

تشير العلامة إلى أنّه لا يتم تسليم البريد كل يوم من أيام الأسبوع. لعرض حرف واحد.

  • Y: لا يتم تسليم البريد كل يوم من أيام الأسبوع.
  • N: ما مِن إشارة إلى أنّه لا يتم تسليم البريد كل يوم من أيام الأسبوع.
dpv_non_delivery_days_values

int32

عدد صحيح يحدّد أيام عدم التسليم يمكن الاستعلام عنه باستخدام علامات بت: 0x40 - الأحد هو يوم لا يتم فيه التسليم 0x20 - الاثنين هو يوم لا يتم فيه التسليم 0x10 - الثلاثاء هو يوم لا يتم فيه التسليم 0x08 - الأربعاء هو يوم لا يتم فيه التسليم 0x04 - الخميس هو يوم لا يتم فيه التسليم 0x02 - الجمعة هو يوم لا يتم فيه التسليم 0x01 - السبت هو يوم لا يتم فيه التسليم
dpv_no_secure_location

string

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

  • Y: لن يتم ترك الطرد بسبب مخاوف تتعلق بالأمان.
  • N: ما مِن مؤشر يشير إلى أنّه لن يتم ترك الطرد بسبب مخاوف تتعلق بالأمان.
dpv_pbsa

string

يشير إلى مطابقة العنوان مع سجلّ PBSA. لعرض حرف واحد.

  • Y: تمت مطابقة العنوان مع سجلّ PBSA.
  • N: لم تتم مطابقة العنوان مع سجلّ PBSA.
dpv_door_not_accessible

string

تشير العلامة إلى العناوين التي لا يمكن لـ USPS النقر على باب لتسليم البريد. تعرض حرفًا واحدًا.

  • Y: يتعذّر الوصول إلى الباب.
  • N: لا تتوفّر أي إشارة إلى أنّه لا يمكن الوصول إلى الباب.
dpv_enhanced_delivery_code

string

يشير هذا الرمز إلى أنّ هناك أكثر من رمز DPV واحد صالح للعنوان. تعرض حرفًا واحدًا.

  • Y: تم تأكيد العنوان DPV للأرقام الأساسية وأي أرقام ثانوية.
  • N: تعذّر على فريق DPV تأكيد معلومات الرقم الأساسي وأي رقم ثانوي.
  • S: تمّ تأكيد DPV للرقم الأساسي فقط، وكانت معلومات الرقم الثانوي متوفّرة ولكن لم يتم تأكيدها، أو تم إسقاط ألفا لاحقة واحدة على رقم أساسي لإجراء مطابقة DPV مع توفير معلومات ثانوية.
  • D: تم تأكيد عنوان DPV للرقم الأساسي فقط، وكانت معلومات الرقم الثانوي غير متوفّرة.
  • R: تم تأكيد العنوان ولكن تم إسناده إلى المسار الوهمي R777 وR779 ولم يتم توفير خدمة التسليم من USPS.
carrier_route

string

رمز مسار مشغِّل شبكة الجوّال رمز مكوّن من أربعة أحرف يتألف من بادئة مكونة من حرف واحد ومؤشر مسار مكوّن من ثلاثة أرقام.

البادئات:

  • C: مسار مشغّل شبكة الجوّال (أو مسار المدينة)
  • ‫R: مسار في منطقة ريفية
  • H: مسار عقد الطريق السريع
  • B: قسم صندوق البريد
  • G: وحدة التسليم العام
carrier_route_indicator

string

مؤشر ترتيب تعرفات مسار شركة النقل
ews_no_match

bool

عنوان التسليم مطابق، إلا أن ملف خدمات Exchange عبر الويب (EWS) يشير إلى أن هناك تطابقًا تامًا ستتوفّر قريبًا.
post_office_city

string

مدينة مكتب البريد الرئيسي
post_office_state

string

حالة المكتب الرئيسي للبريد.
abbreviated_city

string

الاسم المختصر للمدينة.
fips_county_code

string

رمز مقاطعة FIPS
county

string

اسم المقاطعة
elot_number

string

رقم مسار الرحلة المحسّن (eLOT)
elot_flag

string

علامة eLOT تصاعدية/تنازلية (A/D)
po_box_only_postal_code

bool

الرمز البريدي لصندوق البريد فقط
pmb_designator

string

معرّف وحدة PMB (صندوق البريد الخاص)
pmb_number

string

رقم صندوق البريد الخاص (PMB)
address_record_type

string

نوع سجلّ العنوان الذي يتطابق مع العنوان الذي تم إدخاله.

  • F: شركة هذه مطابقة لسجلّ شركة، وهو أعلى مستوى مطابقة متاح لعنوان.
  • G: التسليم العام هذا تطابق مع سجلّ التسليم العام.
  • H: البناء / الشقة هذا الحقل مطابق لسجلّ مبنى أو شقق.
  • P: صندوق البريد هذا تطابق مع صندوق بريد.
  • R: مسار ريفي أو عقد طريق مرتفع: يتطابق هذا العنوان مع سجلّ مسار ريفي أو سجل عقد الطريق السريع، وقد يحتوي كلاهما على نطاقات أرقام صناديق مرتبطة.
  • S: سجلّ الشارع: تشير هذه الحالة إلى تطابق مع سجلّ شارع يحتوي على نطاق أرقام أساسي صالح.
default_address

bool

مؤشر على أنّه تم العثور على عنوان تلقائي، ولكن هناك عناوين أكثر تحديدًا.
error_message

string

رسالة خطأ بشأن استرداد بيانات USPS يتمّ ملء هذا الحقل عند تعليق معالجة USPS بسبب رصد عناوين تم إنشاؤها بشكل مصطنع.

قد لا تتم تعبئة حقول بيانات USPS عند ظهور هذا الخطأ.
cass_processed

bool

مؤشر يشير إلى أنّه تمت معالجة الطلب من خلال CASS

ValidateAddressRequest

طلب التحقّق من عنوان

الحقول
address

PostalAddress

مطلوب. يتم التحقّق من العنوان. يجب إرسال العناوين غير المنسَّقة عبر address_lines.

يجب ألا يتجاوز إجمالي طول الحقول في هذا الإدخال 280 حرفًا.

يمكن الاطّلاع هنا على المناطق التي يتوفّر فيها التطبيق.

القيمة language_code في عنوان الإدخال محجوزة للاستخدامات المستقبلية ويتم تجاهلها اليوم. سيتمّ ملء نتيجة العنوان الذي تم التحقّق منه استنادًا إلى اللغة المفضّلة للعنوان المحدّد، كما حدّدها النظام.

تتجاهل واجهة برمجة تطبيقات التحقق من صحة العناوين القيم في recipients وorganization. وسيتم تجاهل أي قيم في هذه الحقول ولن يتم عرضها. يُرجى عدم ضبطها.
previous_response_id

string

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

bool

لتفعيل الوضع المتوافق مع معيار USPS CASS. لا يؤثر ذلك إلا في حقل google.maps.addressvalidation.v1.ValidationResult.usps_data في google.maps.addressvalidation.v1.ValidationResult. ملاحظة: بالنسبة إلى الطلبات التي تستخدم خدمة USPS CASS للعناوين في بورتوريكو، يجب تقديم google.type.PostalAddress.region_code من address على أنه "PR"، أو يجب تقديم google.type.PostalAddress.administrative_area من address على أنه "بورتوريكو" (غير حساس لحالة الأحرف) أو "PR".

ننصحك باستخدام address مكوّن، أو تحديد google.type.PostalAddress.address_lines على الأقل يتضمّن السطر الأول رقم الشارع واسمه والسطر الثاني المدينة والولاية والرمز البريدي.
language_options

LanguageOptions

اختياريّ. المعاينة: تتوفّر هذه الميزة في مرحلة المعاينة (ما قبل التوفّر للجمهور العام). قد يكون الدعم المقدَّم للمنتجات والميزات في مرحلة ما قبل الإصدار العلني محدودًا، وقد لا تكون التغييرات التي يتم إجراؤها على المنتجات والميزات في مرحلة ما قبل الإصدار العلني متوافقة مع الإصدارات الأخرى من مرحلة ما قبل الإصدار العلني. تخضع "عروض مرحلة ما قبل الإطلاق" للبنود المحدّدة لخدمة Google Maps Platform. لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مرحلة الإطلاق.

يتيح هذا الخيار لواجهة برمجة التطبيقات Address Validation API تضمين معلومات إضافية في الردّ.
session_token

string

اختياريّ. سلسلة تحدِّد جلسة الإكمال التلقائي لأغراض الفوترة يجب أن يكون عنوان URL واسم ملف متوافق مع سلسلة base64 لا يزيد طولها عن 36 حرفًا ASCII. بخلاف ذلك، يتم عرض خطأ INVALID_ARGUMENT.

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

ملاحظة: يمكن استخدام "التحقق من صحة العنوان" في الجلسات فقط مع واجهة برمجة تطبيقات الإكمال التلقائي (الجديدة)، وليس واجهة برمجة التطبيقات الخاصة بميزة "الإكمال التلقائي". يمكنك الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/session-pricing لمعرفة المزيد من التفاصيل.

ValidateAddressResponse

ردّ على طلب التحقّق من عنوان

الحقول
result

ValidationResult

نتيجة عملية إثبات صحة العنوان
response_id

string

معرّف UUID الذي يحدّد هذه الاستجابة. وإذا كانت هناك حاجة إلى إعادة إثبات صحة العنوان، يجب أن يكون المعرّف الفريد العالمي هذا مع الطلب الجديد.

ValidationResult

نتيجة التحقّق من عنوان

الحقول
verdict

Verdict

الإبلاغات العامة عن البيان
address

Address

معلومات عن العنوان نفسه بدلاً من الترميز الجغرافي
geocode

Geocode

معلومات عن الموقع الجغرافي والمكان الذي تم ترميز العنوان جغرافيًا به
metadata

AddressMetadata

معلومات أخرى ذات صلة بإمكانية التسليم لا يمكن ضمان تعبئة الحقل metadata بالكامل لكل عنوان يتم إرساله إلى Address Validation API.
usps_data

UspsData

علامات تسليم إضافية مقدمة من USPS. يتوفّر هذا العرض فقط في المنطقتين US وPR.
english_latin_address

Address

الإصدار التجريبي: تتوفّر هذه الميزة في إصدار تجريبي (قبل طرحها للجميع). قد يكون الدعم المقدَّم للمنتجات والميزات في مرحلة ما قبل الإصدار العلني محدودًا، وقد لا تكون التغييرات التي يتم إجراؤها على المنتجات والميزات في مرحلة ما قبل الإصدار العلني متوافقة مع الإصدارات الأخرى من مرحلة ما قبل الإصدار العلني. تخضع "عروض مرحلة ما قبل الإطلاق" للبنود المحدّدة لخدمة Google Maps Platform. لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق.

تمت ترجمة العنوان إلى الإنجليزية.

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

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

يمكنك تفعيل هذا الإخراج باستخدام العلامة google.maps.addressvalidation.v1.LanguageOptions.return_english_latin_address.

ملاحظة: لا تتم تعبئة حقل google.maps.addressvalidation.v1.Address.unconfirmed_component_types في english_latin_address وحقل google.maps.addressvalidation.v1.AddressComponent.confirmation_level في english_latin_address.address_components.

النتيجة

نظرة عامة عالية المستوى على نتيجة التحقّق من العنوان والرقم الجغرافي

الحقول
input_granularity

Granularity

دقة عنوان الإدخال هذه هي نتيجة تحليل عنوان الإدخال ولا تعطي أي إشارات للتحقّق من الصحة. للحصول على إشارات التحقّق، يُرجى الاطّلاع على validation_granularity أدناه.

على سبيل المثال، إذا كان عنوان الإدخال يتضمّن رقم شقة محدّدًا، سيكون input_granularity هنا هو SUB_PREMISE. إذا لم نتمكّن من مطابقة رقم الشقة في قواعد البيانات أو إذا كان رقم الشقة غير صالح، من المرجّح أن يكون validation_granularity هو PREMISE أو أقل.
validation_granularity

Granularity

مستوى الدقة الذي يمكن لواجهة برمجة التطبيقات التحقّق من العنوان بالكامل. على سبيل المثال، يشير validation_granularity‏= PREMISE إلى أنّه يمكن التحقّق من جميع مكوّنات العنوان على مستوى PREMISE أو أكثر.

يمكن العثور على نتيجة التحقّق من مكوِّنات لكل عنوان في google.maps.addressvalidation.v1.Address.address_components.
geocode_granularity

Granularity

معلومات عن درجة دقة geocode ويمكن فهم ذلك على أنّه المعنى الدلالي لدرجة دقة الموقع الجغرافي المشفَّر جغرافيًا.

قد يختلف هذا التصنيف عن validation_granularity أعلاه في بعض الأحيان. على سبيل المثال، قد تسجِّل قاعدة بياناتنا رقم شقة معيّن، ولكن لا تتضمّن موقعًا جغرافيًا دقيقًا لها ضمن مجمع سكني كبير. في هذه الحالة، سيكون validation_granularity هو SUB_PREMISE ولكن geocode_granularity سيكون PREMISE.
address_complete

bool

يُعتبر العنوان كاملاً إذا لم تكن هناك رموز غير محدّدة أو عناصر عنوان غير متوقّعة أو غير متوفّرة. إذا لم يتم ضبطها، تشير إلى أنّ القيمة هي false. يُرجى الاطّلاع على الحقول "missing_component_types" أو "unresolved_tokens" أو "unexpected" للحصول على مزيد من التفاصيل.
has_unconfirmed_components

bool

لا يمكن تصنيف مكوّن عنوان واحد على الأقل أو التحقّق منه، يُرجى الاطّلاع على google.maps.addressvalidation.v1.Address.address_components لمعرفة التفاصيل.
has_inferred_components

bool

تم استنتاج (إضافة) مكوّن عنوان واحد على الأقل لم يكن مضمّنًا في الإدخال، يُرجى الاطّلاع على google.maps.addressvalidation.v1.Address.address_components لمعرفة التفاصيل.
has_replaced_components

bool

تم استبدال مكوّن عنوان واحد على الأقل، يُرجى الاطّلاع على google.maps.addressvalidation.v1.Address.address_components للاطّلاع على التفاصيل.

الدقة

المستويات المختلفة من الدقة التي يمكن أن يمتلكها العنوان أو الرمز الجغرافي عند استخدامها للإشارة إلى درجة دقة عنوان، تشير هذه القيم إلى درجة الدقة التي يحدّد بها العنوان وجهة إرسال البريد. على سبيل المثال، يحدِّد عنوان مثل "123 Main Street, Redwood City, CA, 94061" PREMISE، في حين يحدِّد عنوان مثل "Redwood City, CA, 94061" LOCALITY. ومع ذلك، إذا لم نتمكن من العثور على رمز جغرافي لـ "123 Main Street" في Redwood City، قد يكون الرمز الجغرافي المعروض بدقة LOCALITY على الرغم من أن العنوان أكثر دقة.

عمليات التعداد
GRANULARITY_UNSPECIFIED القيمة التلقائية. هذه القيمة غير مستخدَمة.
SUB_PREMISE نتيجة على مستوى أقل من مستوى المبنى، مثل شقة
PREMISE نتيجة على مستوى المبنى
PREMISE_PROXIMITY ترميز جغرافي يقترب من الموقع الجغرافي للعنوان على مستوى المبنى
BLOCK يشير العنوان أو الرمز الجغرافي إلى الكتلة. لا يتم استخدامها إلا في المناطق التي تستخدم العناوين على مستوى الكتل، مثل اليابان.
ROUTE يكون الرمز الجغرافي أو العنوان دقيقًا للمسار، مثل شارع أو طريق أو طريق سريع.
OTHER جميع المستويات الأخرى من الدقة، والتي يتم تجميعها معًا لأنّها غير قابلة للعرض