Method: validateAddress

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

طلب HTTP

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

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

نص الطلب

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

تمثيل JSON
{
  "address": {
    object (PostalAddress)
  },
  "previousResponseId": string,
  "enableUspsCass": boolean,
  "languageOptions": {
    object (LanguageOptions)
  }
}
الحقول
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". لمزيد من المعلومات، يمكنك الاطّلاع على أوصاف مرحلة الإطلاق.

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

نص الاستجابة

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

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

تمثيل 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

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

خيارات اللغة

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

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

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

boolean

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

نتائج التحقق من الصحة

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

تمثيل 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)

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

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

geocodeGranularity

enum (Granularity)

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

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

addressComplete

boolean

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

مكوّن العنوان

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

تمثيل 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

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

replaced

boolean

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

unexpected

boolean

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

اسم المكوّن

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

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

string

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

languageCode

string

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

مستوى التأكيد

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

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

plusCode

object (PlusCode)

رمز Plus Codes المقابل للرمز location.

bounds

object (Viewport)

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

featureSizeMeters

number

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

placeId

string

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

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

placeTypes[]

string

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

خط الطول والعرض

كائن يمثل زوجًا من خط العرض/خط الطول. يتم التعبير عن ذلك كزوج من الزوجين لتمثيل خطوط الطول والعرض بالدرجات. يجب أن يتوافق هذا الكائن مع معيار 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 mx14m (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، ولا يمكن أن يكون المربّع الممثل فارغًا (كما هو موضح في التعريفات أعلاه). وسيؤدي إطار العرض الفارغ إلى حدوث خطأ.

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

{ "منخفض": { "خط العرض": 40.477398, "خط الطول": -74.259087 }, "مرتفع": { "خط العرض": 40.91618, "خط الطول": -73.70018 } }

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

object (LatLng)

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

high

object (LatLng)

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

البيانات الوصفية للعنوان

البيانات الوصفية للعنوان. لا يمكن ضمان تعبئة 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,
  "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 للبريد الممسوح ضوئيًا ميكانيًا. يجب أن تؤدي إضافة كل أرقام رمز التسليم_point_barcode وdeliveryPointCheckDigit والرمز البريدي وZIP+4 معًا إلى رقم قابل للقسمة على 10.

dpvConfirmation

string

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

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

string

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

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

string

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

  • Y: العنوان مؤسسة CMRA
  • N: العنوان ليس هيئة CMRA
dpvVacant

string

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

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

string

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

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

string

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

البادئات:

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

string

مؤشر فرز معدل مسار شركة النقل.

ewsNoMatch

boolean

عنوان التسليم قابل للمطابقة، ولكن يشير ملف 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