- طلب HTTP
- نص الطلب
- نص الاستجابة
- PostalAddress
- LanguageOptions
- ValidationResult
- القرار
- درجة الدقة
- العنوان
- AddressComponent
- ComponentName
- ConfirmationLevel
- الرمز الجغرافي
- LatLng
- PlusCode
- إطار العرض
- AddressMetadata
- UspsData
- UspsAddress
للتحقق من صحة أحد العناوين.
طلب HTTP
POST https://addressvalidation.googleapis.com/v1:validateAddress
يستخدم عنوان URL بنية تحويل الترميز gRPC.
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "address": { object ( |
الحقول | |
---|---|
address |
مطلوبة. العنوان الذي يتم التحقق منه. يجب إرسال العناوين غير المنسقة عبر يجب ألا يتجاوز إجمالي طول الحقول في هذا الإدخال 280 حرفًا. يمكن العثور على المناطق التي يتوفّر فيها التطبيق هنا. إنّ القيمة تتجاهل واجهة برمجة تطبيقات التحقّق من صحة العناوين القيم في |
previousResponseId |
يجب أن يكون هذا الحقل فارغًا لطلب التحقق الأول من صحة العنوان. إذا كان من الضروري إجراء المزيد من الطلبات للتحقّق من صحة عنوان واحد بشكل كامل (على سبيل المثال، إذا كانت هناك حاجة إلى إعادة التحقُّق من التغييرات التي يجريها المستخدم بعد عملية التحقّق الأولية)، يجب أن تتم تعبئة هذا الحقل لكل طلب متابعة باستخدام |
enableUspsCass |
يتم تفعيل وضع التوافق مع USPS CASS. ويؤثر هذا فقط في الحقل ننصحك باستخدام سمة |
languageOptions |
اختياريّ. معاينة: تتوفّر هذه الميزة في إصدار المعاينة (ما قبل التوفّر للجمهور العام). قد يكون دعم المنتجات والميزات في مرحلة ما قبل التوفّر للجمهور العام محدودًا، وقد لا تتوافق التغييرات التي تطرأ على منتجات وميزات ما قبل التوفّر للجمهور العام مع الإصدارات الأخرى المتاحة للجمهور العام. تغطي الأحكام الخاصة بخدمة "منصة خرائط Google" "عروض مرحلة ما قبل التوفّر للجمهور العام". لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق. تمكِّن واجهة برمجة تطبيقات التحقّق من صحة العنوان من تضمين معلومات إضافية في الرد. |
sessionToken |
اختياريّ. سلسلة تحدِّد جلسة إكمال تلقائي لأغراض الفوترة. يجب أن تكون السلسلة آمنة من سلسلة base64 لعنوان URL ولها 36 حرف ASCII كحد أقصى. وفي حال عدم تنفيذ ذلك، يتم عرض خطأ POINTS_Quick. تبدأ الجلسة عندما يُجري المستخدم طلب بحث مكتملاً تلقائيًا، وتنتهي عند اختيار مكان وإجراء مكالمة إلى تفاصيل المكان أو التحقُّق من صحة العنوان. يمكن أن تحتوي كل جلسة على طلبات بحث إكمال تلقائي متعددة، متبوعة بطلب التحقق من صحة العنوان أو تفاصيل المكان. يجب أن تنتمي بيانات الاعتماد المستخدَمة لكل طلب خلال جلسة إلى المشروع نفسه على Google Cloud Console. بعد انتهاء الجلسة، لن يصبح الرمز المميز صالحًا، لذا يجب أن ينشئ تطبيقك رمزًا مميزًا جديدًا لكل جلسة. إذا تم حذف مَعلمة ملاحظة: لا يمكن استخدام ميزة "التحقّق من العناوين" إلا في الجلسات التي تتضمّن واجهة برمجة تطبيقات للإكمال التلقائي (جديدة)، وليس واجهة برمجة تطبيقات الإكمال التلقائي. لمزيد من التفاصيل، يمكنك الاطّلاع على https://developers.google.com/maps/documentation/places/web-service/session-pricing. |
نص الاستجابة
الاستجابة لطلب التحقق من العنوان.
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
تمثيل JSON |
---|
{
"result": {
object ( |
الحقول | |
---|---|
result |
نتيجة عملية التحقق من العنوان. |
responseId |
المعرِّف الفريد العالمي (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 |
تمثّل هذه السمة النسخة السابقة من المخطط من |
regionCode |
اختياريّ. رمز CLDR للمنطقة لبلد/منطقة العنوان لمعرفة التفاصيل، يمكنك الاطّلاع على https://cldr.unicode.org/ وhttps://www.unicode.org/cldr/charts/30/supplemental/territory_information.html. مثال: "CH" لسويسرا إذا لم يتم تقديم رمز المنطقة، سيتم استنتاجه من العنوان. لتحقيق أفضل أداء، يُنصح بتضمين رمز المنطقة إذا كنت تعرفه. قد يؤدي استخدام مناطق متكرّرة أو غير متّسقة إلى ضعف الأداء. على سبيل المثال، إذا كانت السمة |
languageCode |
رمز اللغة في عنوان الإدخال محجوز للاستخدامات المستقبلية ويتم تجاهله اليوم. تعرض واجهة برمجة التطبيقات العنوان باللغة المناسبة لمكان العنوان. |
postalCode |
اختياريّ. الرمز البريدي للعنوان إنّ بعض البلدان لا تستخدم الرموز البريدية أو تشترط توفّر هذه الرموز، ولكن في أماكن استخدامها، قد تؤدي إلى إجراء عمليات تحقّق إضافية في أجزاء أخرى من العنوان (على سبيل المثال، التحقق من الولاية أو الرمز البريدي في الولايات المتحدة الأمريكية). |
sortingCode |
اختياريّ. رمز ترتيب إضافي خاص بالبلد ولا يتم استخدام هذه الميزة في معظم المناطق. في حال استخدام هذه القيمة، تكون إما سلسلة مثل "CEDEX" متبوعة برقم اختياري (مثل "CEDEX 7") أو رقم بمفرده يمثل "رمز القطاع" (جامايكا) أو "مؤشر منطقة التسليم" (مالاوي) أو "مؤشر مكتب البريد" (على سبيل المثال، كوت ديفوار). |
administrativeArea |
اختياريّ. أعلى تقسيم فرعي إداري يُستخدم للعناوين البريدية لبلد أو منطقة. على سبيل المثال، يمكن أن تكون ولاية أو مقاطعة أو مقاطعة أو محافظة. وعلى وجه التحديد، بالنسبة إلى إسبانيا، هذه هي الإقليم وليس المجتمع المستقل (مثل "برشلونة" وليس "كاتالونيا"). لا يستخدم العديد من البلدان منطقة إدارية في العناوين البريدية. على سبيل المثال، في سويسرا، يجب ترك هذا الحقل فارغًا. |
locality |
اختياريّ. يشير بوجه عام إلى جزء المدينة/البلدة من العنوان. أمثلة: مدينة في الولايات المتحدة، اتحاد تكنولوجيا المعلومات، مدينة بريد المملكة المتحدة. في المناطق من العالم التي لم يتم تعريفها بشكل جيد أو لا تتناسب مع هذا الهيكل بشكل جيد، اترك المنطقة المحلية فارغة واستخدِم addressLines. |
sublocality |
اختياريّ. المنطقة المحلية الفرعية للعنوان على سبيل المثال، يمكن أن يشمل ذلك الأحياء أو المناطق الإدارية أو الأحياء. |
addressLines[] |
مطلوبة. أسطر عنوان غير مهيكلة تصف المستويات الأدنى من العنوان. |
recipients[] |
يُرجى تجنب ضبط هذا الحقل. لا تستخدمها واجهة برمجة تطبيقات التحقّق من صحة العناوين حاليًا. وعلى الرغم من أنّ واجهة برمجة التطبيقات لن ترفض الطلبات التي تتضمّن مجموعة الحقول هذه في الوقت الحالي، سيتم تجاهل المعلومات ولن يتم عرضها في الردّ. |
organization |
يُرجى تجنب ضبط هذا الحقل. لا تستخدمها واجهة برمجة تطبيقات التحقّق من صحة العناوين حاليًا. وعلى الرغم من أنّ واجهة برمجة التطبيقات لن ترفض الطلبات التي تتضمّن مجموعة الحقول هذه في الوقت الحالي، سيتم تجاهل المعلومات ولن يتم عرضها في الردّ. |
LanguageOptions
معاينة: تتوفّر هذه الميزة في إصدار المعاينة (ما قبل التوفّر للجمهور العام). قد يكون دعم المنتجات والميزات في مرحلة ما قبل التوفّر للجمهور العام محدودًا، وقد لا تتوافق التغييرات التي تطرأ على منتجات وميزات ما قبل التوفّر للجمهور العام مع الإصدارات الأخرى المتاحة للجمهور العام. تغطي الأحكام الخاصة بخدمة "منصة خرائط Google" "عروض مرحلة ما قبل التوفّر للجمهور العام". لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق.
تمكِّن واجهة برمجة تطبيقات التحقّق من صحة العنوان من تضمين معلومات إضافية في الرد.
تمثيل JSON |
---|
{ "returnEnglishLatinAddress": boolean } |
الحقول | |
---|---|
returnEnglishLatinAddress |
معاينة: عرض |
ValidationResult
نتيجة التحقّق من صحة العنوان.
تمثيل JSON |
---|
{ "verdict": { object ( |
الحقول | |
---|---|
verdict |
إجمالي علامات البيان |
address |
معلومات حول العنوان نفسه بدلاً من الرمز الجغرافي. |
geocode |
معلومات حول الموقع الجغرافي والمكان الذي تمّ ترميز العنوان الجغرافي إليه. |
metadata |
معلومات أخرى ذات صلة بالتسليم. لا يمكن ضمان تعبئة |
uspsData |
علامات تسليم إضافية تقدّمها شركة USPS. تم توفير هذه السمة في المنطقتَين |
englishLatinAddress |
معاينة: تتوفّر هذه الميزة في إصدار المعاينة (ما قبل التوفّر للجمهور العام). قد يكون دعم المنتجات والميزات في مرحلة ما قبل التوفّر للجمهور العام محدودًا، وقد لا تتوافق التغييرات التي تطرأ على منتجات وميزات ما قبل التوفّر للجمهور العام مع الإصدارات الأخرى المتاحة للجمهور العام. تغطي الأحكام الخاصة بخدمة "منصة خرائط Google" "عروض مرحلة ما قبل التوفّر للجمهور العام". لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق. تمت ترجمة العنوان إلى اللغة الإنجليزية. لا يمكن إعادة استخدام العناوين المترجَمة كإدخال من واجهة برمجة التطبيقات. وتوفّر الخدمة للمستخدمِين هذه الخدمة ليتمكّنوا من استخدام لغتهم الأم لتأكيد أو رفض التحقّق من صحة العنوان الذي تم تقديمه في الأصل. إذا لم تتوفر ترجمة باللغة الإنجليزية لجزء من العنوان، تعرض الخدمة هذا الجزء بلغة بديلة تستخدم نصًا لاتينيًا. يمكنك النقر هنا للحصول على شرح عن كيفية اختيار اللغة البديلة. إذا لم يكن لجزء من العنوان أي ترجمات أو عمليات تحويل صوتي بلغة تستخدم نصًا لاتينيًا، تعرض الخدمة هذا الجزء باللغة المحلية المرتبطة بالعنوان. ويمكنك تفعيل هذه النتيجة باستخدام العلامة ملاحظة: لا تتم تعبئة الحقل |
النتيجة
نظرة عامة شاملة على نتيجة التحقق من العنوان والرمز الجغرافي.
تمثيل JSON |
---|
{ "inputGranularity": enum ( |
الحقول | |
---|---|
inputGranularity |
دقة عنوان الإدخال. ويأتي هذا نتيجة تحليل عنوان الإدخال ولا يعطي أي إشارات للتحقّق من الصحة. للاطّلاع على إشارات التحقّق من الصحة، يمكنك الرجوع إلى على سبيل المثال، إذا كان عنوان الإدخال يتضمّن رقم شقة معيّنًا، ستكون قيمة |
validationGranularity |
مستوى الدقة الذي يمكن لواجهة برمجة التطبيقات validate من العنوان له بالكامل. على سبيل المثال، تشير قيمة يمكن العثور على نتيجة التحقق من المكوِّن حسب العنوان في |
geocodeGranularity |
تمثّل هذه السمة معلومات عن مستوى دقة يمكن أن يختلف هذا في بعض الأحيان عن |
addressComplete |
يُعد العنوان مكتملاً في حال عدم وجود رموز مميزة لم يتم حلها، أو عدم وجود مكونات عنوان غير متوقعة أو مفقودة. في حال ترك هذه السياسة بدون ضبط، يعني ذلك أنّ القيمة هي |
hasUnconfirmedComponents |
لا يمكن تصنيف مكوّن عنوان واحد على الأقل أو التحقّق من صحته. لمزيد من التفاصيل، يُرجى مراجعة |
hasInferredComponents |
تم استنتاج (تمت إضافة) مكوّن عنوان واحد على الأقل غير مضمّن في الإدخال. يُرجى الاطّلاع على |
hasReplacedComponents |
تم استبدال مكوّن عنوان واحد على الأقل. يُرجى الاطّلاع على |
درجة الدقة
يشير ذلك المصطلح إلى درجات الدقة المختلفة التي يمكن أن يتضمّنها العنوان أو الرمز الجغرافي. وعند استخدامها للإشارة إلى مستوى دقة عنوان، تشير هذه القيم إلى مدى دقة العنوان في تحديد الوجهة البريدية. على سبيل المثال، يحدِّد عنوان مثل "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 ( |
الحقول | |
---|---|
formattedAddress |
العنوان بعد المعالجة، والمنسق كعنوان مكوَّن من سطر واحد وفقًا لقواعد تنسيق العنوان للمنطقة التي يقع فيها العنوان. |
postalAddress |
العنوان الذي تمّت معالجته لاحقًا كعنوان بريدي. |
addressComponents[] |
قائمة بدون ترتيب. مكونات العنوان الفردي للعنوان المنسَّق والصحيح، بالإضافة إلى معلومات التحقّق من الصحة. يوفر هذا معلومات عن حالة التحقق من صحة المكونات الفردية. لا يتم ترتيب مكونات العنوان بطريقة معينة. عدم وضع أي افتراضات بشأن ترتيب مكونات العنوان في القائمة |
missingComponentTypes[] |
تعذّر العثور على أنواع المكوّنات التي كان من المتوقّع وجودها في عنوان بريدي تم تنسيقه بشكل صحيح، ولكن لم يتم العثور عليها في البيانات المعروضة وتعذّر استنتاجها. لا تتوفر مكونات من هذا النوع في |
unconfirmedComponentTypes[] |
تمثّل هذه السمة أنواع المكوّنات المتوفّرة في |
unresolvedTokens[] |
أي رموز مميزة في الإدخال لا يمكن حلها. قد يكون هذا إدخالاً لم يتم التعرف عليه على أنه جزء صالح من العنوان (على سبيل المثال، في إدخال مثل "123235253253 Main St, San Francisco, CA, 94105"، فقد تبدو الرموز المميزة التي لم يتم حلها مثل |
AddressComponent
يمثل عنصر عنوان، مثل شارع أو مدينة أو ولاية.
تمثيل JSON |
---|
{ "componentName": { object ( |
الحقول | |
---|---|
componentName |
اسم هذا المكون. |
componentType |
تمثّل هذه السمة نوع مكوِّن العنوان. راجع الجدول 2: الأنواع الإضافية التي تعرضها خدمة "الأماكن" للحصول على قائمة بالأنواع المحتملة. |
confirmationLevel |
يشير إلى مستوى اليقين الذي لدينا من أن المكون. |
inferred |
تشير هذه السمة إلى أنّ المكوّن لم يكن جزءًا من الإدخال، ولكننا استنتجنا ذلك من موقع العنوان ونعتقد أنّه يجب توفيره للعنوان الكامل. |
spellCorrected |
تشير إلى تصحيح لخطأ إملائي في اسم المكون. لا تُبلِغ واجهة برمجة التطبيقات دائمًا عن التغييرات من صيغة إملائية إلى أخرى، كما هو الحال عند تغيير "مركز" إلى "مركز". ولا يُظهر أيضًا الأخطاء الإملائية الشائعة، مثل تغيير "Amphitheater Pkwy" إلى "Amphitheatre Pkwy". |
replaced |
تشير هذه السمة إلى استبدال اسم المكوّن بآخر مختلف تمامًا، على سبيل المثال، يتم استبدال رمز بريدي خاطئ برمز بريدي صحيح للعنوان. هذا ليس تغييرًا تجميليًا، فقد تم تغيير مكون الإدخال إلى مكوِّن مختلف. |
unexpected |
يشير إلى مكوّن عنوان غير متوقع أن يكون متوفرًا في عنوان بريدي للمنطقة المحددة. وقد تم الاحتفاظ بها لأنها كانت جزءًا من البيانات التي أدخلناها. |
ComponentName
برنامج تضمين لاسم المكون.
تمثيل JSON |
---|
{ "text": string, "languageCode": string } |
الحقول | |
---|---|
text |
نص الاسم. على سبيل المثال، "الجادة الخامسة" لاسم شارع أو "1253" لرقم شارع. |
languageCode |
تمثّل هذه السمة رمز اللغة BCP-47. لن يكون هذا موجودًا إذا كان اسم المكون غير مرتبط بلغة، مثل رقم الشارع. |
ConfirmationLevel
القيم المختلفة المحتملة لمستويات التأكيد.
عمليات التعداد | |
---|---|
CONFIRMATION_LEVEL_UNSPECIFIED |
القيمة التلقائية. هذه القيمة غير مستخدمة. |
CONFIRMED |
تمكنا من التحقق من أن هذا المكون موجود منطقية في سياق بقية العنوان. |
UNCONFIRMED_BUT_PLAUSIBLE |
تعذّر تأكيد هذا العنصر، لكن من المنطقي أنّه موجود. على سبيل المثال، رقم شارع يقع ضمن نطاق أرقام صالح معروف في شارع لا تكون فيه أرقام المنازل المحدّدة معروفة. |
UNCONFIRMED_AND_SUSPICIOUS |
لم يتم تأكيد هذا المكوّن ومن المحتمل أن يكون غير صحيح. على سبيل المثال، حي لا يتناسب مع بقية العنوان. |
الترميز الجغرافي
يحتوي على معلومات حول المكان الذي تم ترميز الإدخال جغرافيًا إليه.
تمثيل JSON |
---|
{ "location": { object ( |
الحقول | |
---|---|
location |
الموقع الجغرافي للإدخال المرمَّز جغرافيًا. يُفضَّل استخدام أرقام تعريف الأماكن على استخدام العناوين أو إحداثيات خطوط الطول والعرض أو رموز الجمع. سوف يؤدي استخدام الإحداثيات عند تحديد مسار القيادة أو حساب اتجاهات القيادة دائمًا إلى انطباق النقطة إلى الطريق الأقرب إلى تلك الإحداثيات. قد لا يكون هذا طريقًا يؤدي بشكل سريع أو آمن إلى الوجهة وقد لا يكون قريبًا من إحدى نقاط الوصول إلى العقار. بالإضافة إلى ذلك، عندما يتم ترميز الموقع الجغرافي بشكل عكسي، ليس هناك ما يضمن تطابق العنوان الذي تم إرجاعه مع العنوان الأصلي. |
plusCode |
تمثّل هذه السمة رمز Plus Codes المتوافق مع |
bounds |
حدود المكان المرمّز جغرافيًا. |
featureSizeMeters |
حجم المكان المرمّز جغرافيًا بالمتر وهذا مقياس آخر لدرجة شدة الموقع الجغرافي المرمَّز جغرافيًا، ولكن في الحجم الفعلي وليس المعنى الدلالي. |
placeId |
رقم تعريف المكان للمكان الذي يتم الترميز الجغرافي لهذا الإدخال إليه. يمكنك الاطّلاع هنا على مزيد من المعلومات عن أرقام تعريف الأماكن. |
placeTypes[] |
نوع(أنواع) المكان الذي تم ترميز الإدخال جغرافيًا إليه. مثلاً: |
LatLng
يشير ذلك المصطلح إلى كائن يمثّل زوجًا من خط العرض/خط الطول. يتم التعبير عن ذلك كزوج من الزوجين لتمثيل خطوط الطول والعرض بالدرجات. يجب أن يتوافق هذا العنصر مع معيار WGS84 ما لم يرد خلاف ذلك. يجب أن تكون القيم ضمن النطاقات التي تمت تسويتها.
تمثيل JSON |
---|
{ "latitude": number, "longitude": number } |
الحقول | |
---|---|
latitude |
تمثّل هذه السمة خط العرض بالدرجات. يجب أن يكون ضمن النطاق [-90.0، +90.0]. |
longitude |
خط الطول بالدرجات. يجب أن يكون ضمن النطاق [-180.0، +180.0]. |
PlusCode
رمز Plus Codes (http://plus.codes) هو مرجع موقع بتنسيقين: رمز عام يحدد 14MX14m (1/8000 من الدرجة) أو مستطيلاً أصغر حجمًا، ورمزًا مركّبًا، حيث يتم استبدال البادئة بالموقع المرجعي.
تمثيل JSON |
---|
{ "globalCode": string, "compoundCode": string } |
الحقول | |
---|---|
globalCode |
الرمز العالمي للمكان (الكامل)، مثل "9FWM33GV+HQ"، الذي يمثّل مساحة 1/8000 x 1/8000 درجة (حوالي 14 × 14 متر) |
compoundCode |
الرمز المركَّب للمكان، مثل "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 ( |
الحقول | |
---|---|
low |
مطلوبة. النقطة المنخفضة لإطار العرض. |
high |
مطلوبة. النقطة المرتفعة لإطار العرض. |
AddressMetadata
البيانات الوصفية للعنوان. لا يمكن ضمان تعبئة metadata
بالكامل لكل عنوان يتم إرساله إلى واجهة برمجة تطبيقات التحقّق من صحة العناوين.
تمثيل JSON |
---|
{ "business": boolean, "poBox": boolean, "residential": boolean } |
الحقول | |
---|---|
business |
يشير إلى أن هذا هو عنوان نشاط تجاري. في حال ترك هذه السياسة بدون ضبط، يعني ذلك أنّ القيمة غير معروفة. |
poBox |
تشير هذه السمة إلى عنوان صندوق البريد. في حال ترك هذه السياسة بدون ضبط، يعني ذلك أنّ القيمة غير معروفة. |
residential |
يشير هذا الرمز إلى أنّ هذا العنوان هو عنوان مسكن. في حال ترك هذه السياسة بدون ضبط، يعني ذلك أنّ القيمة غير معروفة. |
UspsData
بيانات USPS للعنوان لا يمكن ضمان تعبئة uspsData
بالكامل لكل عنوان في الولايات المتحدة أو علاقات عامة يتم إرساله إلى واجهة برمجة تطبيقات التحقّق من صحة العناوين. يُنصَح بدمج حقول العنوان الاحتياطي في الردّ في حال استخدام uspsData كجزء أساسي من الاستجابة.
تمثيل JSON |
---|
{
"standardizedAddress": {
object ( |
الحقول | |
---|---|
standardizedAddress |
عنوان موحّد لـ USPS. |
deliveryPointCode |
رمز نقطة التسليم المكوّن من رقمَين |
deliveryPointCheckDigit |
رقم اختبار نقطة التسليم. تتم إضافة هذا الرقم إلى نهايةdelivery_point_barcode للبريد الذي يتم مسحه ضوئيًا آليًا. يجب أن تؤدي إضافة كل أرقام العنوانdelivery_point_barcode وdeliveryPointCheckDigit والرمز البريدي والرمز ZIP+4 معًا إلى رقم قابل للقسمة على 10. |
dpvConfirmation |
القيم المحتملة لتأكيد DPV. تعرِض حرفًا واحدًا أو لا تعرِض أي قيمة.
|
dpvFootnote |
الحواشي السفلية من التحقق من صحة نقطة التسليم. يمكن دمج الحواشي السفلية المتعددة معًا في السلسلة نفسها.
|
dpvCmra |
يشير إلى ما إذا كان العنوان وكالة CMRA (وكالة استلام البريد التجاري)، وهي مؤسسة خاصة تتلقى البريد للعملاء. تعرِض حرفًا واحدًا.
|
dpvVacant |
هل هذا المكان شاغر؟ تعرِض حرفًا واحدًا.
|
dpvNoStat |
هل هذا العنوان بلا إحصاءات أو عنوان نشط؟ لا توجد عناوين إحصائيات هي العناوين التي لا يتم شغلها بشكل مستمر أو العناوين التي لا تقدم وكالة USPS خدماتها. تعرِض حرفًا واحدًا.
|
dpvNoStatReasonCode |
يشير إلى النوع NoStat. تعرض رمز السبب على أنّه عدد صحيح.
|
dpvDrop |
تشير العلامة إلى تسليم البريد إلى شخص المستلم واحد على أحد المواقع. تعرِض حرفًا واحدًا.
|
dpvThrowback |
يشير إلى عدم تسليم البريد إلى عنوان الشارع. تعرِض حرفًا واحدًا.
|
dpvNonDeliveryDays |
تشير العلامة إلى أنّه لا يتم تسليم البريد في كل يوم من أيام الأسبوع. تعرِض حرفًا واحدًا.
|
dpvNonDeliveryDaysValues |
عدد صحيح لتحديد أيام عدم التسليم يمكن التحقيق في ذلك باستخدام علامات بت: 0x40 - الأحد هو يوم عدم التسليم 0x20 - يوم الاثنين هو يوم عدم التسليم 0x10 - يوم الثلاثاء هو يوم عدم التسليم 0x08 - يوم الثلاثاء هو يوم عدم التسليم 0x08 - ويوم الأربعاء هو يوم عدم التسليم 0x04 - يوم الخميس هو يوم عدم التسليم 0x02 أو يوم الجمعة هو يوم عدم التسليم 0x02 أو يوم الجمعة هو يوم عدم التسليم 0x02 - يوم الجمعة هو يوم عدم التسليم 0x02 أو يوم الجمعة هو يوم عدم التسليم 0x02 |
dpvNoSecureLocation |
تشير العلامة إلى أنّه يمكن الوصول إلى الباب، ولكن لن يتم ترك الطرد لأسباب تتعلّق بالأمان. تعرِض حرفًا واحدًا.
|
dpvPbsa |
يشير إلى مطابقة العنوان مع سجلّ PBSA. تعرِض حرفًا واحدًا.
|
dpvDoorNotAccessible |
تشير العلامة إلى العناوين التي لا يمكن لـ USPS طرقها على الباب لتسليم البريد. تعرِض حرفًا واحدًا.
|
dpvEnhancedDeliveryCode |
تشير هذه القيمة إلى أنّ أكثر من رمز إرجاع DPV واحد صالح للعنوان. تعرِض حرفًا واحدًا.
|
carrierRoute |
رمز مسار مشغّل شبكة الجوّال. رمز مكون من أربعة أحرف يتكون من بادئة حرف واحد ومصمم مسار مكون من ثلاثة أرقام. البادئات:
|
carrierRouteIndicator |
مؤشر فرز معدل مسار مشغّل شبكة الجوّال |
ewsNoMatch |
عنوان التسليم مطابق، لكن ملف EWS يشير إلى أن المطابقة التامة ستتوفر قريبًا. |
postOfficeCity |
المدينة الرئيسية لمكتب البريد. |
postOfficeState |
ولاية مكتب البريد الرئيسي. |
abbreviatedCity |
المدينة المختصرة. |
fipsCountyCode |
رمز FIPS للمقاطعة. |
county |
اسم المقاطعة. |
elotNumber |
رقم خط السفر المحسّن (eLOT). |
elotFlag |
علامة eLOT تصاعدية/تنازلية (A/D). |
lacsLinkReturnCode |
رمز إرجاع LACSLink. |
lacsLinkIndicator |
مؤشر LACSLink |
poBoxOnlyPostalCode |
الرمز البريدي لصندوق البريد فقط |
suitelinkFootnote |
الحواشي السفلية من مطابقة شارع أو سجل شاهق مع معلومات الجناح. في حال العثور على اسم نشاط تجاري مطابق، يتم عرض الرقم الثانوي.
|
pmbDesignator |
مصمّم وحدة صندوق البريد الخاص (PMB). |
pmbNumber |
رقم صندوق البريد الخاص (PMB) |
addressRecordType |
نوع سجلّ العنوان الذي يتطابق مع عنوان الإدخال
|
defaultAddress |
يشير إلى العثور على عنوان تلقائي، ولكن هناك عناوين أكثر تحديدًا. |
errorMessage |
رسالة خطأ لاسترداد بيانات USPS. تتم تعبئة هذه المعلومات عندما يتم تعليق معالجة USPS بسبب رصد عناوين تم إنشاؤها بشكل مصطنع. قد لا تتم تعبئة حقول بيانات USPS عند ظهور هذا الخطأ. |
cassProcessed |
مؤشر على أنه تمت معالجة الطلب باستخدام CASS |
UspsAddress
تمثيل USPS لعنوان في الولايات المتحدة.
تمثيل JSON |
---|
{ "firstAddressLine": string, "firm": string, "secondAddressLine": string, "urbanization": string, "cityStateZipAddressLine": string, "city": string, "state": string, "zipCode": string, "zipCodeExtension": string } |
الحقول | |
---|---|
firstAddressLine |
سطر العنوان الأول. |
firm |
اسم الشركة. |
secondAddressLine |
سطر العنوان الثاني. |
urbanization |
اسم التحضر في بورتوريكو. |
cityStateZipAddressLine |
المدينة والولاية والرمز البريدي |
city |
اسم المدينة |
state |
رمز الولاية المكوّن من حرفين. |
zipCode |
الرمز البريدي، مثل 10009. |
zipCodeExtension |
إضافة الرمز البريدي المكوّنة من 4 أرقام، مثلاً 5023 |