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. ملاحظة: بالنسبة إلى طلبات العناوين في بورتوريكو التي تم تفعيل معيار CASS من USPS لها، يجب تقديم google.type.PostalAddress.region_code من address على أنّه "PR"، أو يجب تقديم google.type.PostalAddress.administrative_area من address على أنّه "بورتوريكو" (لا تُراعَى حالة الأحرف) أو "PR".

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

object (LanguageOptions)

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

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

string

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

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

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

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

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

string

يُرجى تجنُّب ضبط هذا الحقل. ولا تستخدِم واجهة برمجة التطبيقات Address Validation API هذا الإجراء حاليًا. لن ترفض واجهة برمجة التطبيقات في الوقت الحالي الطلبات التي تتضمّن مجموعة الحقول هذه، إلا أنّه سيتم تجاهل المعلومات ولن يتم عرضها في الردّ.
organization

string

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

LanguageOptions

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

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

تمثيل 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 بالكامل لكل عنوان يتم إرساله إلى Address Validation API.
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)

مستوى الدقة الذي يمكن لواجهة برمجة التطبيقات التحقّق من العنوان بالكامل. على سبيل المثال، يشير 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. على سبيل المثال، يمثّل الرمز postalAddress دائمًا البلد على شكل regionCode مكوّن من حرفَين، مثل "US" أو "NZ". في المقابل، يستخدم هذا الحقل صيغة أطول لاسم البلد، مثل "الولايات المتحدة الأمريكية" أو "نيوزيلندا".
postalAddress

object (PostalAddress)

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

object (AddressComponent)

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

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

string

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

string

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

string

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

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

يشير إلى تصحيح خطأ إملائي في اسم المكوِّن. لا تُبلغ واجهة برمجة التطبيقات دائمًا عن التغييرات من صيغة إملائية إلى أخرى، مثل تغيير "centre" إلى "center". ولا تضع دائمًا علامة على الأخطاء الإملائية الشائعة، مثل تغيير "المدرج 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)

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

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

object (PlusCode)

رمز Plus Codes المقابل للموقع الجغرافي 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، رامبرغ، النرويج"، الذي يحتوي على اللاحقة للرمز الشامل ويستبدل البادئة باسم منسَّق لكيان مرجعي

إطار العرض

إطار عرض لخط الطول وخط العرض، ويتم تمثيله كخطين قطريًا مقابل نقطتين 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 بالكامل لكل عنوان يتم إرساله إلى Address Validation API.

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

boolean

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

boolean

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

boolean

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

UspsData

بيانات USPS للعنوان لا يمكن ضمان تعبئة الحقل uspsData بالكامل لكل عنوان في الولايات المتحدة أو في بورتوريكو يتم إرساله إلى Address Validation API. ننصحك بدمج حقول العنوان الاحتياطي في الاستجابة إذا كنت تستخدِم 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، يعني ذلك أنّه لم يتم إرسال العنوان لتأكيد عملية الدفع عبر نقطة البيع.
dpvFootnote

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: الرقم الأساسي الذي تمت مطابقته عن طريق إزالة حرف أبجدي لاحق
dpvCmra

string

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

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

string

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

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

string

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

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

integer

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

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

string

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

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

string

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

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

string

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

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

integer

عدد صحيح يحدد أيام عدم التسليم. يمكن الاستعلام عنه باستخدام علامات بت: 0x40 - الأحد هو يوم لا يتم فيه التسليم 0x20 - الاثنين هو يوم لا يتم فيه التسليم 0x10 - الثلاثاء هو يوم لا يتم فيه التسليم 0x08 - الأربعاء هو يوم لا يتم فيه التسليم 0x04 - الخميس هو يوم لا يتم فيه التسليم 0x02 - الجمعة هو يوم لا يتم فيه التسليم 0x01 - السبت هو يوم لا يتم فيه التسليم
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: RURAL ROUTE أو HIGHWAY CONTRACT: تشير هذه السمة إلى تطابق مع سجلّ Rural Route أو Highway Contract، وكلاهما قد يتضمّن نطاقات مرتبطة بأرقام المربّعات.
  • 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