Method: validateAddress

یک آدرس را تأیید می کند.

درخواست HTTP

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

URL از دستور GRPC Transcoding استفاده می کند.

درخواست بدن

بدنه درخواست حاوی داده هایی با ساختار زیر است:

نمایندگی JSON 
{
  "address": {
    object (PostalAddress)
  },
  "previousResponseId": string,
  "enableUspsCass": boolean,
  "languageOptions": {
    object (LanguageOptions)
  },
  "sessionToken": string
}
فیلدها
address

object ( PostalAddress )

مورد نیاز. آدرس در حال تایید است. آدرس‌های بدون قالب باید از طریق addressLines ارسال شوند.

طول کل فیلدهای این ورودی نباید از 280 کاراکتر تجاوز کند.

مناطق پشتیبانی شده را می توانید در اینجا پیدا کنید.

مقدار languageCode در آدرس ورودی برای استفاده های بعدی محفوظ است و امروز نادیده گرفته می شود. نتیجه آدرس تأیید شده بر اساس زبان ترجیحی برای آدرس داده شده، همانطور که توسط سیستم شناسایی شده است، پر می شود.

Address Validation API مقادیر موجود در recipients و organization را نادیده می گیرد. هر مقدار در آن فیلدها کنار گذاشته می شود و برگردانده نمی شود. لطفا آنها را تنظیم نکنید.

previous Response Id

string

این فیلد باید برای اولین درخواست اعتبارسنجی آدرس خالی باشد. اگر درخواست‌های بیشتری برای اعتبارسنجی کامل یک آدرس ضروری باشد (مثلاً اگر تغییراتی که کاربر پس از تأیید اولیه انجام می‌دهد نیاز به تأیید مجدد داشته باشد)، هر درخواست پیگیری باید از همان اولین پاسخ در این قسمت با responseId پر شود. توالی اعتبار سنجی

enable Usps Cass

boolean

حالت سازگار با USPS CASS را فعال می کند. این فقط فیلد google.maps.addressvalidation.v1.ValidationResult.usps_data google.maps.addressvalidation.v1.ValidationResult را تحت تأثیر قرار می دهد. توجه: برای درخواست‌های دارای USPS CASS برای آدرس‌هایی در پورتوریکو، یک address google.type.PostalAddress.region_code باید به‌عنوان "PR" ارائه شود، یا یک address google.type.PostalAddress.administrative_area باید به عنوان "Puerto" ارائه شود. ریکو" (بدون حساسیت به حروف بزرگ) یا "PR".

توصیه می شود از یک address کامپوننت شده استفاده کنید، یا حداقل دو google.type.PostalAddress.address_lines مشخص کنید که در آن خط اول شامل شماره و نام خیابان و خط دوم شامل شهر، ایالت و کد پستی باشد.

language Options

object ( LanguageOptions )

اختیاری. Preview: این ویژگی در Preview (pre-GA) است. محصولات و ویژگی‌های Pre-GA ممکن است پشتیبانی محدودی داشته باشند، و تغییرات در محصولات و ویژگی‌های pre-GA ممکن است با سایر نسخه‌های pre-GA سازگار نباشد. پیشنهادات قبل از GA تحت پوشش شرایط خاص سرویس پلتفرم Google Maps هستند. برای اطلاعات بیشتر، به توضیحات مرحله راه اندازی مراجعه کنید.

Address Validation API را فعال می کند تا اطلاعات بیشتری را در پاسخ اضافه کند.

session Token

string

اختیاری. رشته ای که یک جلسه تکمیل خودکار را برای اهداف صورتحساب مشخص می کند. باید یک URL و نام فایل ایمن رشته base64 با حداکثر 36 کاراکتر اسکی باشد. در غیر این صورت یک خطای INVALID_ARGUMENT برگردانده می شود.

جلسه زمانی شروع می شود که کاربر یک پرس و جو تکمیل خودکار انجام می دهد، و زمانی که یک مکان را انتخاب می کند و تماسی با جزئیات مکان یا اعتبارسنجی آدرس برقرار می شود، به پایان می رسد. هر جلسه می‌تواند چندین پرس‌وجو تکمیل خودکار داشته باشد و به دنبال آن یک درخواست جزییات مکان یا اعتبارسنجی آدرس ارائه شود. اعتبار استفاده شده برای هر درخواست در یک جلسه باید متعلق به همان پروژه Google Cloud Console باشد. پس از پایان جلسه، رمز دیگر معتبر نیست. برنامه شما باید برای هر جلسه یک توکن جدید تولید کند. اگر پارامتر sessionToken حذف شود، یا اگر از یک نشانه جلسه استفاده مجدد کنید، هزینه جلسه به گونه ای محاسبه می شود که گویی هیچ نشانه جلسه ارائه نشده است (هر درخواست جداگانه صورتحساب می شود).

توجه: اعتبار آدرس فقط در جلسات با API تکمیل خودکار (جدید) قابل استفاده است، نه API تکمیل خودکار. برای جزئیات بیشتر به https://developers.google.com/maps/documentation/places/web-service/session-pricing مراجعه کنید.

بدن پاسخگو

پاسخ به یک درخواست اعتبار سنجی آدرس.

در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی داده هایی با ساختار زیر است:

نمایندگی JSON 
{
  "result": {
    object (ValidationResult)
  },
  "responseId": string
}
فیلدها
result

object ( ValidationResult )

نتیجه اعتبار سنجی آدرس

response Id

string

UUID که این پاسخ را شناسایی می کند. اگر آدرس نیاز به تأیید مجدد داشته باشد، این UUID باید درخواست جدید را همراهی کند.

آدرس پستی

نشان دهنده یک آدرس پستی است، به عنوان مثال برای آدرس های تحویل پستی یا پرداخت. با توجه به آدرس پستی، یک سرویس پستی می تواند اقلام را به محل، صندوق پستی یا موارد مشابه تحویل دهد. مدل سازی مکان های جغرافیایی (جاده ها، شهرها، کوه ها) در نظر گرفته نشده است.

در استفاده معمولی، بسته به نوع فرآیند، یک آدرس از طریق ورودی کاربر یا از وارد کردن داده‌های موجود ایجاد می‌شود.

توصیه‌هایی در مورد ورودی/ویرایش آدرس: - از ویجت آدرس آماده بین‌المللی‌سازی مانند 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 باعث می شود API یک خطای INVALID_ARGUMENT را برگرداند.

region Code

string

اختیاری. کد منطقه CLDR کشور/منطقه آدرس. برای جزئیات به https://cldr.unicode.org/ و https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html مراجعه کنید. مثال: "CH" برای سوئیس. اگر کد منطقه ارائه نشده باشد، از آدرس استنباط می شود. برای بهترین عملکرد، توصیه می‌شود در صورت اطلاع، کد منطقه را نیز وارد کنید. داشتن مناطق ناسازگار یا تکراری می‌تواند منجر به عملکرد ضعیف شود، برای مثال، اگر addressLines قبلاً منطقه را شامل می‌شود، دوباره کد منطقه را در این قسمت ارائه نکنید. مناطق پشتیبانی شده را می توان در پرسش های متداول یافت.

language Code

string

کد زبان در آدرس ورودی برای استفاده های بعدی رزرو شده است و امروز نادیده گرفته می شود. API آدرس را به زبان مناسبی که آدرس در آن قرار دارد برمی گرداند.

postal Code

string

اختیاری. کد پستی آدرس همه کشورها از وجود کدهای پستی استفاده نمی‌کنند یا نیاز به وجود کد پستی ندارند، اما در جایی که از آنها استفاده می‌شود، ممکن است اعتبار سنجی اضافی را با سایر قسمت‌های آدرس (مثلاً اعتبارسنجی ایالت/زیپ در ایالات متحده آمریکا) ایجاد کنند.

sorting Code

string

اختیاری. کد مرتب‌سازی اضافی، خاص کشور. این در اکثر مناطق استفاده نمی شود. در جایی که از آن استفاده می‌شود، مقدار یا رشته‌ای مانند «CEDEX» است، که به صورت اختیاری با یک عدد دنبال می‌شود (مثلاً «CEDEX 7»)، یا فقط یک عدد به تنهایی، نشان‌دهنده «کد بخش» (جامائیکا)، «نشانگر ناحیه تحویل» است. (مالاوی) یا «نشانگر اداره پست» (مثلاً ساحل عاج).

administrative Area

string

اختیاری. بالاترین بخش اداری که برای آدرس های پستی یک کشور یا منطقه استفاده می شود. به عنوان مثال، این می تواند یک ایالت، یک استان، یک استان یا یک استان باشد. به طور خاص، برای اسپانیا این استان است و نه جامعه خودمختار (مثلاً "بارسلونا" و نه "کاتالونیا"). بسیاری از کشورها از یک منطقه اداری در آدرس های پستی استفاده نمی کنند. به عنوان مثال در سوئیس این باید خالی از سکنه بماند.

locality

string

اختیاری. عموماً به بخش شهر/شهرک آدرس اشاره دارد. مثال: شهر ایالات متحده، کمون فناوری اطلاعات، شهر پست بریتانیا. در مناطقی از جهان که محلی ها به خوبی تعریف نشده اند یا به خوبی در این ساختار قرار نمی گیرند، محلی را خالی بگذارید و از خطوط آدرس استفاده کنید.

sublocality

string

اختیاری. موقعیت فرعی آدرس به عنوان مثال، این می تواند محله، محله، منطقه باشد.

address Lines[]

string

مورد نیاز. خطوط آدرس بدون ساختار که سطوح پایین یک آدرس را توصیف می کند.

از آنجایی که مقادیر در addressLines اطلاعات نوع ندارند و گاهی اوقات ممکن است حاوی چندین مقدار در یک فیلد واحد باشند (به عنوان مثال "Austin, TX")، واضح بودن ترتیب خطوط مهم است. ترتیب خطوط آدرس باید "سفارش پاکت" برای کشور/منطقه آدرس باشد.

حداقل نمایش ساختاری مجاز یک آدرس شامل تمام اطلاعاتی است که در addressLines قرار داده شده است. اگر regionCode ارائه نشده باشد، منطقه از خطوط آدرس استنباط می شود.

ایجاد آدرسی که فقط حاوی addressLines باشد و سپس کدگذاری جغرافیایی روشی توصیه شده برای رسیدگی به آدرس‌های کاملاً بدون ساختار است (برخلاف حدس زدن اینکه کدام قسمت‌های آدرس باید محل‌ها یا مناطق اداری باشند).

recipients[]

string

لطفا از تنظیم این فیلد خودداری کنید. Address Validation API در حال حاضر از آن استفاده نمی کند. اگرچه در این زمان API درخواست‌های دارای مجموعه فیلد را رد نمی‌کند، اطلاعات دور ریخته می‌شوند و در پاسخ بازگردانده نمی‌شوند.

organization

string

لطفا از تنظیم این فیلد خودداری کنید. Address Validation API در حال حاضر از آن استفاده نمی کند. اگرچه در این زمان API درخواست‌های دارای مجموعه فیلد را رد نمی‌کند، اطلاعات دور ریخته می‌شوند و در پاسخ بازگردانده نمی‌شوند.

گزینه های زبان

Preview: این ویژگی در Preview (pre-GA) است. محصولات و ویژگی‌های Pre-GA ممکن است پشتیبانی محدودی داشته باشند، و تغییرات در محصولات و ویژگی‌های pre-GA ممکن است با سایر نسخه‌های pre-GA سازگار نباشد. پیشنهادات قبل از GA تحت پوشش شرایط خاص سرویس پلتفرم Google Maps هستند. برای اطلاعات بیشتر، به توضیحات مرحله راه اندازی مراجعه کنید.

Address Validation API را فعال می کند تا اطلاعات بیشتری را در پاسخ اضافه کند.

نمایندگی JSON 
{
  "returnEnglishLatinAddress": boolean
}
فیلدها
return English Latin Address

boolean

پیش نمایش: یک google.maps.addressvalidation.v1.Address را به انگلیسی برگردانید. برای جزئیات به google.maps.addressvalidation.v1.ValidationResult.english_latin_address مراجعه کنید.

نتیجه اعتبارسنجی

نتیجه اعتبارسنجی یک آدرس

نمایندگی JSON 
{
  "verdict": {
    object (Verdict)
  },
  "address": {
    object (Address)
  },
  "geocode": {
    object (Geocode)
  },
  "metadata": {
    object (AddressMetadata)
  },
  "uspsData": {
    object (UspsData)
  },
  "englishLatinAddress": {
    object (Address)
  }
}
فیلدها
verdict

object ( Verdict )

پرچم های حکم کلی

address

object ( Address )

اطلاعات مربوط به خود آدرس بر خلاف ژئوکد.

geocode

object ( Geocode )

اطلاعات مربوط به مکان و مکانی که آدرس به آن کد جغرافیایی داده است.

metadata

object ( AddressMetadata )

سایر اطلاعات مربوط به قابلیت تحویل metadata برای هر آدرسی که به Address Validation API ارسال می شود، تضمین نمی شود.

usps Data

object ( UspsData )

پرچم های تحویل اضافی ارائه شده توسط USPS. فقط در منطقه US و PR ارائه شده است.

english Latin Address

object ( Address )

Preview: این ویژگی در Preview (pre-GA) است. محصولات و ویژگی‌های Pre-GA ممکن است پشتیبانی محدودی داشته باشند، و تغییرات در محصولات و ویژگی‌های pre-GA ممکن است با سایر نسخه‌های pre-GA سازگار نباشد. پیشنهادات قبل از GA تحت پوشش شرایط خاص سرویس پلتفرم Google Maps هستند. برای اطلاعات بیشتر، به توضیحات مرحله راه اندازی مراجعه کنید.

آدرس به انگلیسی ترجمه شده است.

آدرس های ترجمه شده به عنوان ورودی API قابل استفاده مجدد نیستند. این سرویس آنها را فراهم می کند تا کاربر بتواند از زبان مادری خود برای تأیید یا رد اعتبار آدرس ارائه شده اصلی استفاده کند.

اگر بخشی از آدرس دارای ترجمه انگلیسی نباشد، سرویس آن قسمت را به زبان دیگری که از خط لاتین استفاده می کند، برمی گرداند. برای توضیح نحوه انتخاب زبان جایگزین اینجا را ببینید. اگر بخشی از آدرس به زبانی که از خط لاتین استفاده می‌کند ترجمه یا نویسه‌گردانی نداشته باشد، سرویس آن قسمت را به زبان محلی مرتبط با آدرس برمی‌گرداند.

این خروجی را با استفاده از پرچم 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
}
فیلدها
input Granularity

enum ( Granularity )

جزئیات آدرس ورودی این نتیجه تجزیه آدرس ورودی است و هیچ سیگنال اعتبار سنجی نمی دهد. برای سیگنال‌های اعتبارسنجی، به validationGranularity زیر مراجعه کنید.

به عنوان مثال، اگر آدرس ورودی شامل یک شماره آپارتمان خاص باشد، در اینجا inputGranularity SUB_PREMISE خواهد بود. اگر نتوانیم شماره آپارتمان را در پایگاه‌های اطلاعاتی مطابقت دهیم یا شماره آپارتمان نامعتبر باشد، validationGranularity احتمالا PREMISE یا پایین‌تر خواهد بود.

validation Granularity

enum ( Granularity )

سطح دانه بندی که API می تواند آدرس را به طور کامل تأیید کند . به عنوان مثال، validationGranularity از PREMISE نشان می دهد که تمام اجزای آدرس در سطح PREMISE یا بیشتر درشت می توانند اعتبار سنجی شوند.

نتیجه تأیید مؤلفه هر آدرس را می‌توانید در google.maps.addressvalidation.v1.Address.address_components پیدا کنید.

geocode Granularity

enum ( Granularity )

اطلاعات در مورد دانه بندی geocode . این را می توان به عنوان معنای معنایی درشت یا ظریف بودن مکان جغرافیایی درک کرد.

این ممکن است با validationGranularity بالا گاهی اوقات متفاوت باشد. به عنوان مثال، پایگاه داده ما ممکن است وجود یک شماره آپارتمان را ثبت کند اما مکان دقیقی برای آپارتمان در یک مجتمع آپارتمانی بزرگ نداشته باشد. در آن صورت، validationGranularity SUB_PREMISE خواهد بود اما geocodeGranularity PREMISE خواهد بود.

address Complete

boolean

اگر هیچ نشانه حل نشده، هیچ مؤلفه آدرس غیرمنتظره یا گم نشده ای وجود نداشته باشد، آدرس کامل در نظر گرفته می شود. اگر تنظیم نشده باشد، نشان می دهد که مقدار false است. برای جزئیات بیشتر به missingComponentTypes ، unresolvedTokens یا فیلدهای unexpected مراجعه کنید.

has Unconfirmed Components

boolean

حداقل یک جزء آدرس را نمی توان طبقه بندی یا تأیید کرد، برای جزئیات به google.maps.addressvalidation.v1.Address.address_components مراجعه کنید.

has Inferred Components

boolean

حداقل یک جزء آدرس استنباط شد (اضافه شد) که در ورودی نبود، برای جزئیات به google.maps.addressvalidation.v1.Address.address_components مراجعه کنید.

has Replaced Components

boolean

حداقل یک جزء آدرس جایگزین شده است، برای جزئیات به google.maps.addressvalidation.v1.Address.address_components مراجعه کنید.

دانه بندی

دانه بندی های مختلفی که یک آدرس یا یک ژئوکد می تواند داشته باشد. هنگامی که برای نشان دادن جزئیات برای یک آدرس استفاده می‌شود، این مقادیر نشان می‌دهند که آدرس تا چه اندازه یک مقصد پستی را مشخص می‌کند. به عنوان مثال، آدرسی مانند "123 Main Street, Redwood City, CA, 94061" یک PREMISE را مشخص می کند در حالی که چیزی مانند "Redwood City, CA, 94061" یک LOCALITY را مشخص می کند. با این حال، اگر نتوانیم یک ژئوکد برای "خیابان اصلی 123" در شهر ردوود پیدا کنیم، ممکن است ژئوکد ارسالی از LOCALITY دانه بندی باشد، حتی اگر آدرس دقیق تر باشد.

Enums
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
  ]
}
فیلدها
formatted Address

string

آدرس پس از پردازش، به عنوان یک آدرس تک خطی با پیروی از قوانین قالب‌بندی آدرس منطقه‌ای که آدرس در آن قرار دارد، قالب‌بندی شده است.

توجه: قالب این آدرس ممکن است با فرمت آدرس در قسمت postalAddress مطابقت نداشته باشد. برای مثال، postalAddress همیشه کشور را به‌عنوان یک regionCode ۲ حرفی، مانند «US» یا «NZ» نشان می‌دهد. در مقابل، این فیلد از شکل طولانی‌تری از نام کشور مانند «USA» یا «نیوزیلند» استفاده می‌کند.

postal Address

object ( PostalAddress )

آدرس پس از پردازش به عنوان یک آدرس پستی نشان داده شده است.

address Components[]

object ( AddressComponent )

لیست نامرتب اجزای آدرس منفرد آدرس فرمت شده و تصحیح شده، همراه با اطلاعات اعتبارسنجی. این اطلاعات در مورد وضعیت اعتبار سنجی اجزای جداگانه ارائه می دهد.

اجزای آدرس به روش خاصی مرتب نمی شوند. هیچ گونه فرضی در مورد ترتیب اجزای آدرس در لیست انجام ندهید.

missing Component Types[]

string

انواع مؤلفه هایی که انتظار می رفت در یک آدرس پستی با فرمت صحیح وجود داشته باشند اما در ورودی و یافت نشدند قابل استنباط نیستند. مؤلفه‌های این نوع در formattedAddress ، postalAddress ، یا addressComponents وجود ندارند. یک مثال ممکن است ['street_number', 'route'] برای ورودی مانند "Boulder, Colorado, 80301, USA" باشد. لیست انواع ممکن را می توان در اینجا یافت.

unconfirmed Component Types[]

string

انواع مؤلفه‌هایی که در addressComponents وجود دارند، اما صحت آنها تأیید نشد. این فیلد به منظور راحتی ارائه شده است: محتویات آن معادل تکرار از طریق addressComponents برای یافتن انواع همه مؤلفه‌هایی است که در آن confirmationLevel CONFIRMED نشده است یا پرچم inferred روی true تنظیم نشده است. لیست انواع ممکن را می توان در اینجا یافت.

unresolved Tokens[]

string

هر نشانه ای در ورودی که قابل حل نیست. ممکن است این ورودی باشد که به عنوان بخشی معتبر از یک آدرس شناسایی نشده باشد. به عنوان مثال، برای ورودی‌هایی مانند «Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US»، نشانه‌های حل‌نشده ممکن است مانند ["Parcel", "0000123123", "&", "0000456456"] باشند.

Address Component

نشان دهنده یک جزء آدرس، مانند یک خیابان، شهر یا ایالت است.

نمایندگی JSON 
{
  "componentName": {
    object (ComponentName)
  },
  "componentType": string,
  "confirmationLevel": enum (ConfirmationLevel),
  "inferred": boolean,
  "spellCorrected": boolean,
  "replaced": boolean,
  "unexpected": boolean
}
فیلدها
component Name

object ( ComponentName )

نام این جزء

component Type

string

نوع جزء آدرس جدول 2 را ببینید: انواع اضافی که توسط سرویس Places برگردانده شده است برای لیستی از انواع احتمالی.

confirmation Level

enum ( ConfirmationLevel )

نشان دهنده میزان اطمینانی است که ما در مورد صحیح بودن مؤلفه داریم.

inferred

boolean

نشان می دهد که مؤلفه بخشی از ورودی نبوده است، اما ما آن را برای مکان آدرس استنباط کردیم و معتقدیم که باید برای یک آدرس کامل ارائه شود.

spell Corrected

boolean

تصحیح یک غلط املایی در نام مؤلفه را نشان می دهد. API همیشه تغییرات را از یک نوع املایی به دیگری علامت گذاری نمی کند، مانند زمانی که "مرکز" به "مرکز" تغییر می کند. همچنین همیشه اشتباهات املایی رایج را علامت گذاری نمی کند، مانند زمانی که "Amphitheatre Pkwy" را به "Amphitheatre Pkwy" تغییر می دهید.

replaced

boolean

نشان می دهد که نام مؤلفه با یک نام کاملاً متفاوت جایگزین شده است، به عنوان مثال یک کد پستی اشتباه با کدی که برای آدرس صحیح است جایگزین شده است. این یک تغییر زیبایی نیست، جزء ورودی به دیگری تغییر کرده است.

unexpected

boolean

یک جزء آدرس را نشان می دهد که انتظار نمی رود در آدرس پستی منطقه داده شده وجود داشته باشد. ما آن را فقط به این دلیل حفظ کرده ایم که بخشی از ورودی بوده است.

نام مؤلفه

یک لفاف برای نام جزء.

نمایندگی JSON 
{
  "text": string,
  "languageCode": string
}
فیلدها
text

string

متن نام. به عنوان مثال، "5th Avenue" برای نام یک خیابان یا "1253" برای یک شماره خیابان.

language Code

string

کد زبان BCP-47. اگر نام مؤلفه با زبانی مانند شماره خیابان مرتبط نباشد، این مورد وجود نخواهد داشت.

سطح تایید

مقادیر مختلف ممکن برای سطوح تایید.

Enums
CONFIRMATION_LEVEL_UNSPECIFIED مقدار پیش فرض این مقدار استفاده نشده است.
CONFIRMED ما توانستیم تأیید کنیم که این مؤلفه در زمینه بقیه آدرس وجود دارد و منطقی است.
UNCONFIRMED_BUT_PLAUSIBLE این مؤلفه قابل تأیید نیست، اما وجود آن قابل قبول است. به عنوان مثال، یک شماره خیابان در محدوده معتبر شناخته شده اعداد در خیابانی که شماره خانه های خاصی در آن مشخص نیست.
UNCONFIRMED_AND_SUSPICIOUS این مؤلفه تأیید نشد و احتمالاً اشتباه است. مثلا محله ای که به بقیه آدرس نمی خورد.

ژئوکد

حاوی اطلاعاتی درباره مکانی است که ورودی در آن کدگذاری شده است.

نمایندگی JSON 
{
  "location": {
    object (LatLng)
  },
  "plusCode": {
    object (PlusCode)
  },
  "bounds": {
    object (Viewport)
  },
  "featureSizeMeters": number,
  "placeId": string,
  "placeTypes": [
    string
  ]
}
فیلدها
location

object ( LatLng )

مکان جغرافیایی کد شده ورودی.

استفاده از شناسه‌های مکان بر استفاده از آدرس‌ها، مختصات طول و عرض جغرافیایی یا کدهای بعلاوه ترجیح داده می‌شود. استفاده از مختصات هنگام مسیریابی یا محاسبه مسیرهای رانندگی همیشه باعث می شود که نقطه به نزدیکترین جاده به آن مختصات گیر کند. ممکن است این جاده ای نباشد که به سرعت یا ایمن به مقصد منتهی شود و ممکن است نزدیک یک نقطه دسترسی به ملک نباشد. علاوه بر این، هنگامی که یک مکان معکوس جغرافیایی کدگذاری می شود، هیچ تضمینی وجود ندارد که آدرس برگشتی با آدرس اصلی مطابقت داشته باشد.

plus Code

object ( PlusCode )

کد مثبت مربوط به location .

bounds

object ( Viewport )

محدوده مکان ژئوکد شده.

feature Size Meters

number

اندازه مکان ژئوکد شده، بر حسب متر. این یکی دیگر از معیارهای درشت بودن مکان جغرافیایی کد شده است، اما در اندازه فیزیکی به جای معنای معنایی.

place Id

string

شناسه مکان مکانی که این ورودی به آن کد جغرافیایی می‌دهد.

برای اطلاعات بیشتر درباره شناسه‌های مکان اینجا را ببینید.

place Types[]

string

نوع(های) مکانی که ورودی به آن کدگذاری شده است. برای مثال، ['locality', 'political'] . لیست کامل انواع را می توان در اینجا یافت.

LatLng

شیئی که نشان دهنده یک جفت طول و عرض جغرافیایی است. این به صورت یک جفت دوتایی برای نشان دادن درجه عرض جغرافیایی و درجه طول جغرافیایی بیان می شود. مگر اینکه طور دیگری مشخص شده باشد، این شی باید با استاندارد WGS84 مطابقت داشته باشد. مقادیر باید در محدوده نرمال شده باشند.

نمایندگی JSON 
{
  "latitude": number,
  "longitude": number
}
فیلدها
latitude

number

عرض جغرافیایی بر حسب درجه باید در محدوده [-90.0، +90.0] باشد.

longitude

number

طول جغرافیایی بر حسب درجه باید در محدوده [-180.0، +180.0] باشد.

پلاس کد

کد پلاس ( http://plus.codes ) یک مرجع مکان با دو قالب است: کد جهانی که مستطیل 14mx14m (1/8000 درجه) یا کوچکتر را تعریف می کند و کد ترکیبی که پیشوند را با یک مکان مرجع جایگزین می کند.

نمایندگی JSON 
{
  "globalCode": string,
  "compoundCode": string
}
فیلدها
global Code

string

کد جهانی (کامل) مکان، مانند "9FWM33GV+HQ"، که یک منطقه 1/8000 در 1/8000 درجه (~14 در 14 متر) را نشان می دهد.

compound Code

string

کد ترکیبی Place، مانند "33GV+HQ، Ramberg، Norway"، حاوی پسوند کد جهانی و جایگزینی پیشوند با نام قالب بندی شده یک نهاد مرجع.

درگاه دید

یک نمای طول و عرض جغرافیایی که به صورت دو نقطه low و high به صورت مورب در مقابل هم نمایش داده می شود. یک viewport یک منطقه بسته در نظر گرفته می شود، یعنی شامل مرز آن می شود. محدوده عرض جغرافیایی باید بین 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, "Litude": -74.259087 }, "high": { "Latitude": 40.91618, "Latitude": -73.70018 } }

نمایندگی JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
فیلدها
low

object ( LatLng )

مورد نیاز. نقطه پایین دید.

high

object ( LatLng )

مورد نیاز. نقطه اوج دید.

AddressMetadata

فراداده برای آدرس. metadata برای هر آدرسی که به Address Validation API ارسال می شود، تضمین نمی شود.

نمایندگی JSON 
{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}
فیلدها
business

boolean

نشان می دهد که این آدرس یک کسب و کار است. اگر تنظیم نشده باشد، نشان دهنده ناشناخته بودن مقدار است.

po Box

boolean

نشان می دهد که آدرس یک صندوق پستی. اگر تنظیم نشده باشد، نشان دهنده ناشناخته بودن مقدار است.

residential

boolean

نشان می دهد که این آدرس یک محل سکونت است. اگر تنظیم نشده باشد، نشان دهنده ناشناخته بودن مقدار است.

UspsData

داده های USPS برای آدرس. uspsData برای هر آدرس ایالات متحده یا روابط عمومی ارسال شده به Address Validation API تضمین نمی شود که به طور کامل پر شود. اگر از 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
}
فیلدها
standardized Address

object ( UspsAddress )

آدرس استاندارد USPS

delivery Point Code

string

کد نقطه تحویل 2 رقمی

delivery Point Check Digit

string

رقم بررسی نقطه تحویل این شماره به انتهای بارکد_point_delivery برای نامه های اسکن شده مکانیکی اضافه می شود. با جمع کردن تمام ارقام delivery_point_barcode، deliveryPointCheckDigit، کد پستی و ZIP+4 باید عددی قابل بخش بر 10 به دست آید.

dpv Confirmation

string

مقادیر ممکن برای تایید DPV. یک کاراکتر را برمی‌گرداند یا هیچ مقداری را برمی‌گرداند.

  • N : اطلاعات اعداد اولیه و ثانویه تأیید DPV نشد.
  • D : آدرس فقط برای شماره اولیه DPV تأیید شد و اطلاعات شماره ثانویه وجود نداشت.
  • S : آدرس فقط برای شماره اولیه DPV تأیید شد و اطلاعات شماره ثانویه موجود بود اما تأیید نشد.
  • Y : آدرس DPV برای شماره های اولیه و ثانویه تایید شد.
  • خالی: اگر پاسخ حاوی مقدار dpvConfirmation نباشد، آدرس برای تأیید DPV ارسال نشده است.
dpv Footnote

string

پاورقی از اعتبار سنجی نقطه تحویل. ممکن است چندین پاورقی در یک رشته به هم متصل شوند.

  • AA : آدرس ورودی با فایل ZIP+4 مطابقت دارد
  • A1 : آدرس ورودی با فایل ZIP+4 مطابقت نداشت
  • BB : مطابق با DPV (همه اجزا)
  • CC : شماره ثانویه مطابقت ندارد و لازم نیست
  • C1 : شماره ثانویه مطابقت ندارد اما لازم است
  • N1 : آدرس بلند مرتبه فاقد شماره ثانویه است
  • M1 : شماره اولیه وجود ندارد
  • M3 : شماره اصلی نامعتبر است
  • P1 : آدرس ورودی PO، RR یا شماره جعبه HC موجود نیست
  • P3 : آدرس ورودی PO، RR یا شماره جعبه HC نامعتبر است
  • F1 : آدرس ورودی مطابق با یک آدرس نظامی است
  • G1 : آدرس ورودی با یک آدرس تحویل عمومی مطابقت دارد
  • U1 : آدرس ورودی مطابق با یک کد پستی منحصر به فرد
  • PB : آدرس ورودی با رکورد PBSA مطابقت دارد
  • RR : آدرس تأیید شده توسط DPV با اطلاعات PMB
  • R1 : آدرس تایید شده DPV بدون اطلاعات PMB
  • R7 : رکورد مسیر حامل R777 یا R779
  • IA : آدرس آگاه شناسایی شد
  • TA : عدد اولیه با حذف یک آلفای انتهایی مطابقت دارد
dpv Cmra

string

نشان می دهد که آیا آدرس یک CMRA (آژانس دریافت نامه های تجاری) است - یک کسب و کار خصوصی که نامه دریافت می کند برای مشتریان. یک کاراکتر را برمی‌گرداند.

  • Y : آدرس یک CMRA است
  • N : آدرس یک CMRA نیست
dpv Vacant

string

آیا این مکان خالی است؟ یک کاراکتر را برمی‌گرداند.

  • Y : آدرس خالی است
  • N : آدرس خالی نیست
dpv No Stat

string

آیا این یک آدرس بدون آمار است یا یک آدرس فعال؟ هیچ آدرس آماری، آدرس هایی نیستند که به طور مداوم اشغال نمی شوند یا آدرس هایی که USPS سرویس نمی دهد. یک کاراکتر را برمی‌گرداند.

  • Y : آدرس فعال نیست
  • N : آدرس فعال است
dpv No Stat Reason Code

integer

نوع NoStat را نشان می دهد. یک کد دلیل را به عنوان int برمی گرداند.

  • 1 : IDA (Internal Drop Address) - آدرس هایی که ایمیل را مستقیماً از USPS دریافت نمی کنند اما به آدرس drop تحویل داده می شوند که به آنها خدمات ارائه می دهد.
  • 2 : CDS - آدرس هایی که هنوز قابل تحویل نیستند. به عنوان مثال، یک بخش فرعی جدید که در آن قطعات و اعداد اولیه تعیین شده است، اما هنوز ساختاری برای اشغال وجود ندارد.
  • 3 : برخورد - آدرس هایی که در واقع DPV را تأیید نمی کنند.
  • 4 : CMZ (کالج، نظامی و انواع دیگر) - ZIP + 4 رکورد USPS در داده ها گنجانده شده است.
  • 5 : معمولی - نشان دهنده آدرس هایی است که تحویل دریافت نمی کنند و آدرس ها به عنوان تحویل های احتمالی محاسبه نمی شوند.
  • 6 : ثانویه مورد نیاز - آدرس به اطلاعات ثانویه نیاز دارد.
dpv Drop

string

پرچم نشان می‌دهد که نامه‌ها به یک مورد در یک سایت تحویل داده می‌شود. یک کاراکتر را برمی‌گرداند.

  • Y : نامه به یک نفر در یک سایت تحویل داده می شود.
  • N : نامه به یک فرد قابل دریافت در یک سایت تحویل داده نمی شود.
dpv Throwback

string

نشان می دهد که نامه به آدرس خیابان تحویل داده نمی شود. یک کاراکتر را برمی‌گرداند.

  • Y : نامه به آدرس خیابان تحویل داده نمی شود.
  • N : نامه به آدرس خیابان تحویل داده می شود.
dpv Non Delivery Days

string

پرچم نشان می دهد که تحویل نامه در هر روز هفته انجام نمی شود. یک کاراکتر را برمی‌گرداند.

  • Y : تحویل پست هر روز هفته انجام نمی شود.
  • N : هیچ نشانه ای وجود ندارد که تحویل نامه در هر روز هفته انجام نمی شود.
dpv Non Delivery Days Values

integer

تعداد صحیح شناسایی روزهای بدون تحویل می توان آن را با استفاده از پرچم های بیت بازجویی کرد: 0x40 - یکشنبه یک روز بدون تحویل است 0x20 - دوشنبه یک روز بدون تحویل است 0x10 - سه شنبه یک روز بدون تحویل است 0x08 - چهارشنبه یک روز بدون تحویل است 0x04 - پنجشنبه یک روز غیر تحویل است -روز تحویل 0x02 - جمعه یک روز بدون تحویل است 0x01 - شنبه یک روز بدون تحویل است

dpv No Secure Location

string

پرچم نشان می دهد که درب قابل دسترسی است، اما بسته به دلیل نگرانی های امنیتی باقی نخواهد ماند. یک کاراکتر را برمی‌گرداند.

  • Y : بسته به دلیل نگرانی های امنیتی باقی نخواهد ماند.
  • N : هیچ نشانه ای وجود ندارد که بسته به دلیل نگرانی های امنیتی باقی نمی ماند.
dpv Pbsa

string

نشان می دهد که آدرس با رکورد PBSA مطابقت داده شده است. یک کاراکتر را برمی‌گرداند.

  • Y : آدرس با رکورد PBSA مطابقت داشت.
  • N : آدرس با رکورد PBSA مطابقت نداشت.
dpv Door Not Accessible

string

پرچم نشان‌دهنده آدرس‌هایی است که USPS نمی‌تواند برای تحویل نامه به درب بزند. یک کاراکتر را برمی‌گرداند.

  • Y : در قابل دسترس نیست.
  • N : هیچ نشانه ای وجود ندارد که درب قابل دسترسی نیست.
dpv Enhanced Delivery Code

string

نشان می دهد که بیش از یک کد بازگشتی DPV برای آدرس معتبر است. یک کاراکتر را برمی‌گرداند.

  • Y : آدرس DPV برای شماره های اولیه و ثانویه تایید شد.
  • N : اطلاعات اعداد اولیه و ثانویه تأیید DPV نشد.
  • S : آدرس فقط برای شماره اولیه DPV تأیید شد، و اطلاعات شماره ثانویه موجود بود اما تأیید نشد، یا یک آلفای انتهایی روی یک شماره اولیه حذف شد تا مطابقت DPV و اطلاعات ثانویه مورد نیاز باشد.
  • D : آدرس فقط برای شماره اولیه DPV تأیید شد و اطلاعات شماره ثانویه وجود نداشت.
  • R : آدرس تأیید شده است اما به مسیر فانتوم R777 و R779 اختصاص داده شده است و تحویل USPS ارائه نشده است.
carrier Route

string

کد مسیر حامل یک کد چهار کاراکتری متشکل از یک پیشوند یک حرفی و یک نشانگر مسیر سه رقمی.

پیشوندها:

  • C : مسیر حامل (یا مسیر شهری)
  • R : مسیر روستایی
  • H : مسیر قرارداد بزرگراه
  • B : بخش صندوق پست
  • G : واحد تحویل عمومی
carrier Route Indicator

string

نشانگر مرتب‌سازی نرخ مسیر حامل.

ews No Match

boolean

آدرس تحویل قابل تطبیق است، اما فایل EWS نشان می دهد که به زودی یک تطابق دقیق در دسترس خواهد بود.

post Office City

string

شهر پست اصلی

post Office State

string

ایالت اداره پست اصلی

abbreviated City

string

شهر به اختصار.

fips County Code

string

کد شهرستان FIPS.

county

string

نام شهرستان.

elot Number

string

شماره خط سفر پیشرفته (eLOT).

elot Flag

string

پرچم صعودی/نزولی eLOT (A/D).

po Box Only Postal Code

boolean

کد پستی فقط صندوق پستی

pmb Designator

string

تعیین کننده واحد PMB (جعبه پست خصوصی).

pmb Number

string

شماره PMB (صندوق پست خصوصی)؛

address Record Type

string

نوع رکورد آدرسی که با آدرس ورودی مطابقت دارد.

  • F : شرکت. این تطبیق با یک سابقه شرکت است، که بهترین سطح تطابق موجود برای یک آدرس است.
  • G : تحویل عمومی. این یک مسابقه با رکورد تحویل عمومی است.
  • H : ساختمان / آپارتمان. این یک تطابق با رکورد ساختمان یا آپارتمان است.
  • P : صندوق پستی. این مطابق با صندوق پستی است.
  • R : قرارداد مسیر روستایی یا بزرگراه: این مطابق با رکورد یک مسیر روستایی یا یک قرارداد بزرگراه است، که هر دو ممکن است محدوده‌های Box Number مرتبط داشته باشند.
  • S : STREET RECORD: این تطبیق با یک رکورد خیابانی است که دارای محدوده اعداد اولیه معتبر است.
default Address

boolean

نشان می دهد که یک آدرس پیش فرض پیدا شده است، اما آدرس های خاص تری وجود دارد.

error Message

string

پیام خطا برای بازیابی اطلاعات USPS. زمانی که پردازش USPS به دلیل شناسایی آدرس‌های ایجاد شده مصنوعی به حالت تعلیق در می‌آید، پر می‌شود.

فیلدهای داده USPS ممکن است در صورت وجود این خطا پر نشوند.

cass Processed

boolean

نشانگر این است که درخواست CASS پردازش شده است.

آدرس Usps

نمایندگی USPS از یک آدرس ایالات متحده.

نمایندگی JSON 
{
  "firstAddressLine": string,
  "firm": string,
  "secondAddressLine": string,
  "urbanization": string,
  "cityStateZipAddressLine": string,
  "city": string,
  "state": string,
  "zipCode": string,
  "zipCodeExtension": string
}
فیلدها
first Address Line

string

خط اول آدرس

firm

string

نام شرکت

second Address Line

string

خط آدرس دوم

urbanization

string

نام شهرنشینی پورتوریکویی

city State Zip Address Line

string

شهر + ایالت + کد پستی.

city

string

نام شهر.

state

string

کد دولتی 2 حرفی

zip Code

string

کد پستی به عنوان مثال 10009.

zip Code Extension

string

پسوند کد پستی 4 رقمی به عنوان مثال 5023.