Method: validateAddress

{
  "revision": integer,
  "regionCode": string,
  "languageCode": string,
  "postalCode": string,
  "sortingCode": string,
  "administrativeArea": string,
  "locality": string,
  "sublocality": string,
  "addressLines": [
    string
  ],
  "recipients": [
    string
  ],
  "organization": string
}

integer

مراجعة مخطط PostalAddress. وستتسبب أي قيمة غير 0 في عرض واجهة برمجة التطبيقات للخطأ INVALID_ARGUMENT.

string

اختياريّ. رمز منطقة CLDR للبلد/المنطقة للعنوان. راجع https://cldr.unicode.org/ وhttps://www.unicode.org/cldr/charts/30/supplemental/territory_information.html للحصول على التفاصيل. مثال: "CH" لسويسرا. إذا لم يتم تقديم رمز المنطقة، سيتم استنتاجه من العنوان. للحصول على أفضل أداء، ننصح بتضمين رمز المنطقة إذا كنت تعرفه. قد يؤدي عدم اتساق المناطق أو تكرارها إلى ضعف الأداء، على سبيل المثال، إذا كان addressLines يتضمن المنطقة مسبقًا، لا تُدخل رمز المنطقة مرة أخرى في هذا الحقل. يمكن العثور على المناطق المتوافقة في الأسئلة الشائعة.

string

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

string

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

string

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

string

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

string

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

string

اختياريّ. المنطقة الفرعية للعنوان. على سبيل المثال: يمكن أن يتمثل ذلك في أحياء، أحياء، مقاطعات.

string

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

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

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

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

string

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

string

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

{
  "verdict": {
    object (Verdict)
  },
  "address": {
    object (Address)
  },
  "geocode": {
    object (Geocode)
  },
  "metadata": {
    object (AddressMetadata)
  },
  "uspsData": {
    object (UspsData)
  }
}

object (Verdict)

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

object (Address)

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

object (Geocode)

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

object (AddressMetadata)

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

object (UspsData)

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

{
  "inputGranularity": enum (Granularity),
  "validationGranularity": enum (Granularity),
  "geocodeGranularity": enum (Granularity),
  "addressComplete": boolean,
  "hasUnconfirmedComponents": boolean,
  "hasInferredComponents": boolean,
  "hasReplacedComponents": boolean
}

enum (Granularity)

دقة عنوان الإدخال. ويحدث ذلك نتيجة تحليل عنوان الإدخال ولا يعطي أي إشارات تحقُّق. للحصول على إشارات التحقق، يمكنك الرجوع إلى validationGranularity أدناه.

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

enum (Granularity)

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

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

enum (Granularity)

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

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

boolean

يُعتبر العنوان مكتملاً إذا لم تكن هناك رموز مميزة لم تُحَل، ولم تكن هناك مكونات عنوان غير متوقعة أو مفقودة. يمكنك الاطّلاع على الحقول missingComponentTypes أو unresolvedTokens أو unexpected للحصول على مزيد من التفاصيل.

boolean

يتعذّر تصنيف مكوّن عنوان واحد على الأقل أو التحقّق من صحته. يمكنك الاطّلاع على google.maps.addressvalidation.v1.Address.address_components لمعرفة التفاصيل.

boolean

تم استنتاج (إضافة) مكوِّن عنوان واحد على الأقل لم يتم إدخاله، يُرجى الاطّلاع على google.maps.addressvalidation.v1.Address.address_components لمعرفة التفاصيل.

boolean

تم استبدال مكون عنوان واحد على الأقل، اطّلع على google.maps.addressvalidation.v1.Address.address_components لمعرفة التفاصيل.

{
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "addressComponents": [
    {
      object (AddressComponent)
    }
  ],
  "missingComponentTypes": [
    string
  ],
  "unconfirmedComponentTypes": [
    string
  ],
  "unresolvedTokens": [
    string
  ]
}

string

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

object (PostalAddress)

العنوان الذي تم التحقق من صحته والممثّل كعنوان بريدي.

object (AddressComponent)

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

لم يتم ترتيب مكوّنات العنوان بطريقة معينة. لا تقدم أي افتراضات حول ترتيب مكونات العنوان في القائمة.

string

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

string

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

string

أي رموز مميزة في الإدخال لم يتم حلها. قد يكون هذا إدخالاً لم يتم التعرف عليه باعتباره جزءًا صالحًا من أحد العناوين (على سبيل المثال، في إدخال مثل "123235253253 الشارع الرئيسي، سان فرانسيسكو، كاليفورنيا، 94105"، قد تبدو الرموز المميزة التي لم يتم حلها كـ ["123235253253"] نظرًا لأنها لا تبدو كرقم شارع صالح.

{
  "componentName": {
    object (ComponentName)
  },
  "componentType": string,
  "confirmationLevel": enum (ConfirmationLevel),
  "inferred": boolean,
  "spellCorrected": boolean,
  "replaced": boolean,
  "unexpected": boolean
}

object (ComponentName)

اسم هذا المكوِّن.

string

نوع مكوّن العنوان. راجع الجدول 2: الأنواع الإضافية التي تعرضها خدمة الأماكن للحصول على قائمة بالأنواع المحتملة.

enum (ConfirmationLevel)

يشير إلى مستوى اليقين الذي لدينا للتأكد من أن المكون صحيح.

boolean

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

boolean

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

boolean

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

boolean

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

{
  "text": string,
  "languageCode": string
}

string

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

string

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

{
  "location": {
    object (LatLng)
  },
  "plusCode": {
    object (PlusCode)
  },
  "bounds": {
    object (Viewport)
  },
  "featureSizeMeters": number,
  "placeId": string,
  "placeTypes": [
    string
  ]
}

object (LatLng)

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

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

object (PlusCode)

رمز الموقع المفتوح المقابل لـ location.

object (Viewport)

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

number

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

string

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

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

string

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

{
  "latitude": number,
  "longitude": number
}

number

خط العرض بالدرجات. ويجب أن يقع ضمن النطاق [-90.0 أو +90.0].

number

خط الطول بالدرجات. ويجب أن تقع ضمن النطاق [-180.0، +180.0].

{
  "globalCode": string,
  "compoundCode": string
}

string

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

string

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

{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}

object (LatLng)

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

object (LatLng)

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

{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}

boolean

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

boolean

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

boolean

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

{
  "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
}

object (UspsAddress)

عنوان USPS القياسي.

string

رمز نقطة التسليم المكوّن من رقمين

string

رقم التحقق من نقطة التسليم تتم إضافة هذا الرقم إلى نهاية رمز التسليم_الشريطي_للبريد الذي تم مسحه ضوئيًا بشكل ميكانيكي. من المفترض أن تؤدي إضافة جميع الأرقام لـ delivery_point_barcode وdeliveryPointCheckDigit والرمز البريدي والرمز البريدي+4 معًا إلى الحصول على رقم قابل للقسمة على 10.

string

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

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

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

string

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

• Y: العنوان هو CMRA
• N: العنوان ليس CMRA.

string

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

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

string

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

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

string

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

البادئات:

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

string

مؤشر ترتيب معدّل مسار شركة النقل

boolean

عنوان التسليم متطابق، ولكن يشير ملف EWS إلى أن هناك تطابقًا تامًا سيكون متاحًا قريبًا.

string

مدينة مكتب البريد الرئيسية.

string

الولاية الرئيسية لمكتب البريد.

string

مدينة مختصرة.

string

رمز مقاطعة FIPS.

string

اسم المقاطعة.

string

رقم خط السفر المحسن (eLOT).

string

علامة eLOT تصاعدي/تنازلي (أ/د).

string

رمز إرجاع LACSLink.

string

مؤشر LACSLink.

boolean

الرمز البريدي لصندوق البريد فقط.

string

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

• A: مطابقة سجل رابط Suite، تم تحسين عنوان النشاط التجاري.
• 00: لا يوجد تطابق، لم يتم تحسين عنوان النشاط التجاري.

string

محدد وحدة (PMB) (البريد الخاص).

string

رقم PMB (صندوق البريد الخاص)؛

string

نوع سجل العنوان الذي يتطابق مع عنوان الإدخال.

• F: شركة. ويتطابق هذا مع سجلّ الشركة، وهو أعلى مستوى من التطابق المتاح للعنوان.
• G: تسليم عام. يتطابق هذا مع أحد سجلات التسليم العام.
• H: المبنى / الشقة. يتطابق هذا مع سجلّ مبنى أو شقة.
• P: صندوق بريد مكتبي. يتطابق هذا مع مربع مكتب البريد.
• R: مسار عقاري أو عقد طريق سريع: يتطابق هذا المسار مع مسار ريفي أو سجل عقد طريق سريع، وكلاهما قد يكون مقترنًا بنطاقات أرقام مربعة.
• S: سجل الشارع: يتطابق هذا مع سجل في الشارع يشتمل على نطاق رقمي أساسي صالح.

boolean

إشارة إلى أنه تم العثور على عنوان تلقائي، ولكن هناك عناوين أكثر تحديدًا.

string

رسالة خطأ استرداد بيانات USPS. تتمّ تعبئة هذا الحقل عندما يتمّ تعليق معالجة USPS بسبب رصد عناوين تمّ إنشاؤها بطريقة مصطنعة.

قد لا تتم تعبئة حقول بيانات USPS عند وجود هذا الخطأ.

boolean

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

{
  "firstAddressLine": string,
  "firm": string,
  "secondAddressLine": string,
  "urbanization": string,
  "cityStateZipAddressLine": string,
  "city": string,
  "state": string,
  "zipCode": string,
  "zipCodeExtension": string
}

string

السطر الأول من العنوان.

string

اسم الشركة.

string

السطر الثاني من العنوان.

string

اسم المنطقة الحضرية في بورتوريكو.

string

المدينة + الولاية + الرمز البريدي.

string

اسم المدينة.

string

رمز حالة مكوّن من حرفين.

string

الرمز البريدي مثل 10009.

string

إضافة رمز بريدي مكوّنة من 4 أرقام، مثل 5023.