Method: validateAddress

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

طلب HTTP

POST https://addressvalidation.googleapis.com/v1:validateAddress

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "address": {
    object (PostalAddress)
  },
  "previousResponseId": string,
  "enableUspsCass": boolean,
  "languageOptions": {
    object (LanguageOptions)
  },
  "sessionToken": string
}
الحقول
address

object (PostalAddress)

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

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

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

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

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

string

يجب أن يكون هذا الحقل فارغًا لطلب التحقّق من العنوان الأول. إذا كانت هناك حاجة إلى المزيد من الطلبات للتحقّق من صحة عنوان واحد بالكامل (على سبيل المثال، إذا كانت التغييرات التي يجريها المستخدم بعد عملية التحقّق الأولية بحاجة إلى إعادة التحقّق)، يجب عندئذٍ كل طلب متابعة تعبئة هذا الحقل بـ responseId من الاستجابة الأولى في تسلسل التحقّق.
enableUspsCass

boolean

لتفعيل الوضع المتوافق مع معيار 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 على الأقل حيث يحتوي السطر الأول على رقم الشارع واسمه، ويحتوي السطر الثاني على المدينة والولاية والرمز البريدي.
languageOptions

object (LanguageOptions)

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

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

string

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

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

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

نص الاستجابة

تمثّل هذه السمة الاستجابة لطلب التحقّق من العنوان.

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "result": {
    object (ValidationResult)
  },
  "responseId": string
}
الحقول
result

object (ValidationResult)

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

string

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

PostalAddress

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

في الاستخدام النموذجي، يتم إنشاء عنوان من خلال البيانات التي يُدخلها المستخدم أو من استيراد البيانات الحالية، وذلك حسب نوع العملية.

نصائح بشأن إدخال العنوان أو تعديله: - استخدام تطبيق مصغّر بعنوان جاهز للاستخدام مع مختلف البلدان، مثل https://github.com/google/libaddressinput). يجب عدم تقديم عناصر واجهة المستخدم إلى المستخدمين لإدخال أو تعديل الحقول خارج البلدان التي يُستخدَم فيها هذا الحقل.

لمزيد من الإرشادات حول كيفية استخدام هذا المخطط، يُرجى الاطّلاع على: https://support.google.com/business/answer/6397478

تمثيل JSON 
{
  "revision": integer,
  "regionCode": string,
  "languageCode": string,
  "postalCode": string,
  "sortingCode": string,
  "administrativeArea": string,
  "locality": string,
  "sublocality": string,
  "addressLines": [
    string
  ],
  "recipients": [
    string
  ],
  "organization": string
}
الحقول
revision

integer

تمثّل هذه السمة مراجعة المخطط لـ PostalAddress. أمّا القيمة الأخرى غير 0، فستعرض واجهة برمجة التطبيقات الخطأ INVALID_ARGUMENT.
regionCode

string

اختياريّ. رمز CLDR للبلد أو المنطقة التي يقع فيها العنوان. يمكنك الانتقال إلى https://cldr.unicode.org/ وhttps://www.unicode.org/cldr/charts/30/supplemental/territory_information.html لمعرفة التفاصيل. مثال: "CH" بالنسبة إلى الإمارات. إذا لم يتم تقديم رمز المنطقة، سيتم استنتاجه من العنوان. ولتحقيق أفضل أداء، ننصحك بتضمين رمز المنطقة إذا كنت تعرفه. قد يؤدي عدم اتّساق المناطق أو تكرارها إلى ضعف الأداء. على سبيل المثال، إذا كانت السمة addressLines تتضمّن المنطقة حاليًا، لا تقدّم رمز المنطقة مرّة أخرى في هذا الحقل. يمكن العثور على المناطق المتوافقة في الأسئلة الشائعة.
languageCode

string

رمز اللغة في عنوان الإدخال محجوز للاستخدامات المستقبلية وسيتم تجاهله اليوم. تعرض واجهة برمجة التطبيقات العنوان باللغة المناسبة للمكان الذي يقع فيه العنوان.
postalCode

string

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

string

اختياريّ. رمز ترتيب إضافي خاص بالبلد. لا تُستخدم هذه الميزة في معظم المناطق. وعند استخدامها، تكون القيمة إما سلسلة مثل "CEDEX"، متبوعة اختياريًا برقم (مثل "CEDEX 7")، أو مجرد رقم وحده، يمثّل "رمز القطاع" (جامايكا) أو "مؤشر منطقة التسليم" (مالاوي) أو "مؤشر مكتب البريد" (مثل ساحل العاج).
administrativeArea

string

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

string

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

string

اختياريّ. المنطقة المحلية الفرعية للعنوان. على سبيل المثال، يمكن أن تكون الأحياء أو المناطق الإدارية أو المناطق.
addressLines[]

string

مطلوبة. أسطر عنوان غير منظمة تصف المستويات الأدنى من العنوان.

بما أنّ القيم في addressLines لا تحتوي على معلومات النوع وقد تحتوي أحيانًا على قيم متعددة في حقل واحد (مثل "أوستن، تكساس")، من المهم أن يكون ترتيب الأسطر واضحًا. يجب أن يكون ترتيب أسطر العنوان هو "طلب على شكل غلاف" للبلد أو المنطقة التي يقع فيها العنوان.

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

إنشاء عنوان يحتوي على addressLines فقط، ثم الترميز الجغرافي هو الطريقة الموصى بها للتعامل مع العناوين غير المنظَّمة تمامًا (بدلاً من تخمين أجزاء العنوان التي يجب أن تكون لمناطق محلية أو إدارية).
recipients[]

string

يُرجى تجنُّب ضبط هذا الحقل. ولا تستخدمها حاليًا واجهة برمجة تطبيقات التحقق من صحة العنوان. على الرغم من أنّ واجهة برمجة التطبيقات لن ترفض الطلبات التي تتضمّن مجموعة الحقول هذه في الوقت الحالي، سيتم تجاهل المعلومات ولن يتم عرضها في الردّ.
organization

string

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

LanguageOptions

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

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

تمثيل JSON 
{
  "returnEnglishLatinAddress": boolean
}
الحقول
returnEnglishLatinAddress

boolean

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

ValidationResult

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

تمثيل JSON 
{
  "verdict": {
    object (Verdict)
  },
  "address": {
    object (Address)
  },
  "geocode": {
    object (Geocode)
  },
  "metadata": {
    object (AddressMetadata)
  },
  "uspsData": {
    object (UspsData)
  },
  "englishLatinAddress": {
    object (Address)
  }
}
الحقول
verdict

object (Verdict)

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

object (Address)

معلومات حول العنوان نفسه وليس الرمز الجغرافي.
geocode

object (Geocode)

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

object (AddressMetadata)

تمثّل هذه السمة معلومات أخرى ذات صلة بالتسليم. ليس من المضمون تعبئة metadata بالكامل لكل عنوان يتم إرساله إلى واجهة برمجة تطبيقات التحقُّق من صحة العناوين.
uspsData

object (UspsData)

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

object (Address)

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

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

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

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

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

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

النتيجة

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

تمثيل JSON 
{
  "inputGranularity": enum (Granularity),
  "validationGranularity": enum (Granularity),
  "geocodeGranularity": enum (Granularity),
  "addressComplete": boolean,
  "hasUnconfirmedComponents": boolean,
  "hasInferredComponents": boolean,
  "hasReplacedComponents": boolean
}
الحقول
inputGranularity

enum (Granularity)

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

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

enum (Granularity)

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

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

enum (Granularity)

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

قد يختلف هذا التصنيف عن validationGranularity أعلاه في بعض الأحيان. على سبيل المثال، قد تسجل قاعدة البيانات لدينا وجود رقم شقة ولكنها لا تحتوي على موقع دقيق للشقة داخل مجمع سكني كبير. وفي هذه الحالة، ستكون قيمة validationGranularity هي SUB_PREMISE لكن قيمة geocodeGranularity ستكون PREMISE.
addressComplete

boolean

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

boolean

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

boolean

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

boolean

تم استبدال مكوّن عنوان واحد على الأقل. يُرجى الاطّلاع على 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 جميع درجات الدقة الأخرى، التي يتم تجميعها معًا نظرًا لأنها غير قابلة للتسليم.

العنوان

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

تمثيل JSON 
{
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "addressComponents": [
    {
      object (AddressComponent)
    }
  ],
  "missingComponentTypes": [
    string
  ],
  "unconfirmedComponentTypes": [
    string
  ],
  "unresolvedTokens": [
    string
  ]
}
الحقول
formattedAddress

string

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

object (PostalAddress)

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

object (AddressComponent)

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

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

string

تعذّر استنتاج أنواع المكوّنات التي كان من المتوقّع وجودها في عنوان بريدي بتنسيق صحيح ولكن لم يتم العثور عليها في الإدخال، وتعذّر استنتاجها. مكوّنات هذا النوع غير متوفّرة في formattedAddress أو postalAddress أو addressComponents. من الأمثلة على ذلك ['street_number', 'route'] لإدخال، مثل "بولدر، كولورادو، 80301، الولايات المتحدة". يمكن الاطّلاع على قائمة الأنواع المحتمَلة هنا.
unconfirmedComponentTypes[]

string

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

string

يشير هذا المصطلح إلى أي رموز مميّزة في الإدخال لم نتمكّن من حلّها. قد يكون ذلك إدخالاً لم يتم التعرّف عليه كجزء من عنوان صالح (على سبيل المثال، في إدخال مثل "123235253253 Main St, San Francisco, CA, 94105"، قد تبدو الرموز المميزة التي لم يتم حلها بالتنسيق ["123235253253"] لأنّ ذلك لا يبدو رقم شارع صالحًا.

AddressComponent

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

تمثيل JSON 
{
  "componentName": {
    object (ComponentName)
  },
  "componentType": string,
  "confirmationLevel": enum (ConfirmationLevel),
  "inferred": boolean,
  "spellCorrected": boolean,
  "replaced": boolean,
  "unexpected": boolean
}
الحقول
componentName

object (ComponentName)

اسم هذا المكون.
componentType

string

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

enum (ConfirmationLevel)

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

boolean

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

boolean

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

boolean

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

boolean

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

ComponentName

برنامج تضمين لاسم المكوِّن.

تمثيل JSON 
{
  "text": string,
  "languageCode": string
}
الحقول
text

string

نص الاسم. على سبيل المثال، يمكنك استخدام "الجادة الخامسة" لاسم الشارع أو "1253" لرقم الشارع.
languageCode

string

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

ConfirmationLevel

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

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

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

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

تمثيل JSON 
{
  "location": {
    object (LatLng)
  },
  "plusCode": {
    object (PlusCode)
  },
  "bounds": {
    object (Viewport)
  },
  "featureSizeMeters": number,
  "placeId": string,
  "placeTypes": [
    string
  ]
}
الحقول
location

object (LatLng)

الموقع المرمَّز جغرافيًا للإدخال.

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

object (PlusCode)

تمثّل هذه السمة رمز الموقع المفتوح المقابل لـ location.
bounds

object (Viewport)

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

number

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

string

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

لمزيد من المعلومات عن أرقام تعريف الأماكن، اطّلِع هنا.
placeTypes[]

string

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

LatLng

كائن يمثّل زوجًا من خط العرض/الطول ويتم التعبير عن ذلك في صورة زوج من الزوجين لتمثيل درجات الطول والعرض والدرجات. ما لم يُنص على خلاف ذلك، يجب أن يتوافق هذا العنصر مع معيار WGS84. يجب أن تكون القيم ضمن النطاقات التي تمت تسويتها.

تمثيل JSON 
{
  "latitude": number,
  "longitude": number
}
الحقول
latitude

number

خط العرض بالدرجات. يجب أن يكون في النطاق [ -90.0، +90.0].
longitude

number

خط الطول بالدرجات. يجب أن يكون في النطاق [ -180.0، +180.0].

PlusCode

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

تمثيل JSON 
{
  "globalCode": string,
  "compoundCode": string
}
الحقول
globalCode

string

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

string

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

إطار العرض

إطار عرض لخط الطول والعرض، ويتم تمثيله كخطين قطريًا مقابل نقطتين low وhigh. يُعتبَر إطار العرض منطقة مغلقة، بمعنى أنه يتضمّن حدوده. يجب أن تتراوح حدود خطوط العرض بين -90 و90 درجة، ويجب أن تتراوح حدود خط الطول بين -180 و180 درجة كحد أقصى. تشمل الحالات المختلفة ما يلي:

  • إذا كانت low = high، يتكوّن إطار العرض من هذه النقطة الفردية.

  • إذا كانت low.longitude > high.longitude، يتم قلب نطاق خط الطول (يتقاطع إطار العرض مع خط الطول بمقدار 180 درجة).

  • إذا كانت قيمة low.longitude = -180 درجة وhigh.longitude = 180 درجة، يشمل إطار العرض جميع خطوط الطول.

  • إذا كانت low.longitude = 180 درجة وhigh.longitude = -180 درجة، يكون نطاق خط الطول فارغًا.

  • إذا كانت low.latitude > high.latitude، سيكون نطاق خط العرض فارغًا.

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

على سبيل المثال، يشمل إطار العرض هذا مدينة نيويورك بالكامل:

{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }

تمثيل JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
الحقول
low

object (LatLng)

مطلوبة. النقطة المنخفضة في إطار العرض.
high

object (LatLng)

مطلوبة. تمثّل هذه السمة النقطة العليا لإطار العرض.

AddressMetadata

البيانات الوصفية للعنوان. ليس من المضمون تعبئة metadata بالكامل لكل عنوان يتم إرساله إلى واجهة برمجة تطبيقات التحقُّق من صحة العناوين.

تمثيل JSON 
{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}
الحقول
business

boolean

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

boolean

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

boolean

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

UspsData

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

تمثيل JSON 
{
  "standardizedAddress": {
    object (UspsAddress)
  },
  "deliveryPointCode": string,
  "deliveryPointCheckDigit": string,
  "dpvConfirmation": string,
  "dpvFootnote": string,
  "dpvCmra": string,
  "dpvVacant": string,
  "dpvNoStat": string,
  "dpvNoStatReasonCode": integer,
  "dpvDrop": string,
  "dpvThrowback": string,
  "dpvNonDeliveryDays": string,
  "dpvNonDeliveryDaysValues": integer,
  "dpvNoSecureLocation": string,
  "dpvPbsa": string,
  "dpvDoorNotAccessible": string,
  "dpvEnhancedDeliveryCode": string,
  "carrierRoute": string,
  "carrierRouteIndicator": string,
  "ewsNoMatch": boolean,
  "postOfficeCity": string,
  "postOfficeState": string,
  "abbreviatedCity": string,
  "fipsCountyCode": string,
  "county": string,
  "elotNumber": string,
  "elotFlag": string,
  "lacsLinkReturnCode": string,
  "lacsLinkIndicator": string,
  "poBoxOnlyPostalCode": boolean,
  "suitelinkFootnote": string,
  "pmbDesignator": string,
  "pmbNumber": string,
  "addressRecordType": string,
  "defaultAddress": boolean,
  "errorMessage": string,
  "cassProcessed": boolean
}
الحقول
standardizedAddress

object (UspsAddress)

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

string

رمز نقطة تسليم من رقمَين
deliveryPointCheckDigit

string

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

string

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

  • N: تعذَّر تأكيد DPV لمعلومات الرقم الأساسي وأي رقم ثانوي.
  • D: تم تأكيد DPV للرقم الأساسي فقط، ولم تتوفّر معلومات الرقم الثانوي.
  • S: تم تأكيد عنوان DPV للرقم الأساسي فقط، وكانت معلومات الرقم الثانوي متوفّرة ولكن لم يتم تأكيدها.
  • Y: تم تأكيد العنوان DPV للأرقام الأساسية وأي أرقام ثانوية.
  • فارغ: إذا لم يتضمّن الردّ قيمة dpvConfirmation، هذا يعني أنّه لم يتم إرسال العنوان لتأكيد DPV.
dpvFootnote

string

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

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

string

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

  • Y: العنوان هو قانون CMRA
  • N: العنوان ليس حساب CMRA
dpvVacant

string

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

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

string

هل هذا العنوان بدون إحصاءات أم أن هذا العنوان نشط؟ ليست هناك عناوين للإحصائيات هي العناوين التي لا مشغولة بشكل مستمر أو التي لا تقدم خدمة USPS خدماتها. تعرض حرفًا واحدًا.

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

integer

يشير إلى نوع NoStat. تعرض رمز السبب على هيئة int.

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

string

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

  • Y: يتم تسليم البريد إلى مُستلم واحد في موقع إلكتروني.
  • N: لا يتم تسليم البريد إلى جهاز مُستلم واحد في أحد المواقع الإلكترونية.
dpvThrowback

string

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

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

string

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

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

integer

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

string

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

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

string

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

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

string

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

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

string

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

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

string

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

البادئات:

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

string

مؤشر ترتيب معدل مسارات شركات النقل.
ewsNoMatch

boolean

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

string

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

string

ولاية مكتب البريد الرئيسية.
abbreviatedCity

string

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

string

رمز المقاطعة FIPS.
county

string

اسم المقاطعة.
elotNumber

string

رقم خط السفر المحسّن (eLOT).
elotFlag

string

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

boolean

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

string

محدِّد وحدة PMB (صندوق البريد الخاص).
pmbNumber

string

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

string

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

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

boolean

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

string

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

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

boolean

مؤشر على اكتمال معالجة الطلب CASS

UspsAddress

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

تمثيل JSON 
{
  "firstAddressLine": string,
  "firm": string,
  "secondAddressLine": string,
  "urbanization": string,
  "cityStateZipAddressLine": string,
  "city": string,
  "state": string,
  "zipCode": string,
  "zipCodeExtension": string
}
الحقول
firstAddressLine

string

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

string

اسم الشركة.
secondAddressLine

string

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

string

اسم التحضر في بورتوريكو.
cityStateZipAddressLine

string

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

string

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

string

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

string

الرمز البريدي مثل 10009.
zipCodeExtension

string

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