Method: validateAddress

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

طلب HTTP

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

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

نص الطلب

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

تمثيل JSON
{
  "address": {
    object (PostalAddress)
  },
  "previousResponseId": string,
  "enableUspsCass": boolean
}
الحقول
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 على الأقل حيث يحتوي السطر الأول على رقم الشارع والاسم ويحتوي السطر الثاني على المدينة والولاية والرمز البريدي.

نص الاستجابة

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

الاستجابة لطلب التحقق من العنوان.

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

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

نتيجة التحقق

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

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

object (Verdict)

علامات القرار العام

address

object (Address)

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

geocode

object (Geocode)

معلومات حول الموقع والمكان اللذين تم ترميزهما جغرافيًا بالعنوان.

metadata

object (AddressMetadata)

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

uspsData

object (UspsData)

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

النتيجة

نظرة عامة عالية المستوى على نتيجة التحقق من العنوان والشكل الجغرافي.

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

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

replaced

boolean

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

unexpected

boolean

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

اسم المكوّن

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

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

string

نص الاسم. على سبيل المثال، "الشارع الخامس" لاسم الشارع أو "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)

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

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

plusCode

object (PlusCode)

رمز الموقع المفتوح المقابل لـ 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].

رمز الموقع المفتوح

رمز الموقع المفتوح (http://plus.codes) هو مرجع موقع بتنسيقين: رمز عام يحدد 14mx14m (1/8000th of a degrees) أو مستطيل صغير، ورمزًا مركبًا، ويستبدل البادئة بموقع مرجعي.

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

string

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

compoundCode

string

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

إطار العرض

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

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

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

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

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

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

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

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

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

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

object (LatLng)

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

high

object (LatLng)

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

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

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

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

boolean

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

poBox

boolean

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

residential

boolean

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

بيانات USps

بيانات 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 وdeliveryPointCheckDigit والرمز البريدي والرمز البريدي+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: لم يتم إدخال RR أو رقم صندوق مركز المساعدة في إدخال العنوان
  • P3: رقم أمر الشراء أو رقم RR أو رقم صندوق مركز المساعدة غير صالح
  • F1: عنوان إدخال مطابق لعنوان عسكري
  • G1: عنوان إدخال مطابق لعنوان تسليم عام
  • U1: عنوان إدخال مطابق لرمز بريدي فريد
  • PB: عنوان إدخال مطابق لسجل PBSA
  • RR: تم تأكيد عنوان DPV مع معلومات مدير النشاط التجاري
  • 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 تصاعدي/تنازلي (أ/د).

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

مؤشر على أنه قد تمت معالجة طلب CAS.

عنوان USps

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