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) الذي يعرّف هذه الاستجابة في حال كان هناك حاجة إلى إعادة إثبات صحة العنوان، يجب أن يتم إرفاق معرّف 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")، أو رقم فقط يمثّل "رمز القطاع" (Jamaica) أو "مؤشر منطقة التسليم" (مالاوي) أو "مؤشر مكتب البريد" (مثل ساحل العاج).

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

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

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

replaced

boolean

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

unexpected

boolean

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

ComponentName

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

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

string

نص الاسم. على سبيل المثال، "5 شارع" لاسم شارع أو "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) هو مرجع موقع جغرافي بتنسيقَين: رمز عام يحدّد 14mx14m (1/8000 درجة من الدرجة) أو مستطيلاً أصغر حجمًا، ورمز مركّب، يتم استبدال البادئة فيه بالموقع المرجعي.

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

string

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

compoundCode

string

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

إطار العرض

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

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

  • 1: IDA (عنوان البريد الإلكتروني الداخلي) - العناوين التي لا تتلقى الرسائل الإلكترونية مباشرة من 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 – الأحد هو يوم عدم التسليم 0x20 – يوم الاثنين هو يوم عدم التسليم 0x10 – يوم الثلاثاء هو يوم عدم التسليم 0x10 – الثلاثاء هو يوم عدم التسليم 0x08 – الأربعاء هو يوم عدم التسليم 0x04 – يوم الخميس هو يوم عدم التسليم 0x02 – يوم الأحد هو يوم عدم التسليم 0x02 – يوم الجمعة هو يوم عدم التسليم 0x02 – يوم الثلاثاء هو يوم عدم التسليم 0x02 – يوم الثلاثاء هو يوم عدم التسليم 0x02 – يوم السبت هو يوم عدم التسليم 0x02 – يوم السبت هو يوم عدم التسليم 0x02 – يوم الجمعة

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

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

يشير إلى أن الطلب قد تمت معالجته.

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