Method: validateAddress

מאמת כתובת.

בקשת HTTP

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

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "address": {
    object (PostalAddress)
  },
  "previousResponseId": string,
  "enableUspsCass": boolean,
  "languageOptions": {
    object (LanguageOptions)
  },
  "sessionToken": string
}
שדות
address

object (PostalAddress)

חובה. הכתובת בתהליך אימות. כתובות לא מעוצבות יש לשלוח דרך addressLines.

האורך הכולל של השדות בקלט הזה לא יכול לחרוג מ-280 תווים.

כאן מפורטים האזורים הנתמכים.

הערך languageCode בכתובת הקלט שמור לשימושים עתידיים והמערכת מתעלמת ממנו היום. התוצאה של הכתובת המאומתת תאוכלס בהתאם לשפה המועדפת של הכתובת הנתונה, כפי שהמערכת תזהה.

ה-API לאימות כתובת מתעלם מהערכים ב-recipients וב-organization. כל הערכים בשדות האלה יימחקו ולא יוחזרו. אין להגדיר אותן.
previousResponseId

string

השדה הזה חייב להיות ריק בבקשה הראשונה לאימות הכתובת. אם נדרשות בקשות נוספות כדי לאמת באופן מלא כתובת יחידה (לדוגמה, אם השינויים שהמשתמש מבצע אחרי האימות הראשוני צריך לאמת מחדש), כל בקשת המשך צריכה לאכלס את השדה הזה ב-responseId מהתגובה הראשונה ברצף האימות.
enableUspsCass

boolean

הפעלת מצב תואם ל-USPS CASS. הפעולה הזו משפיעה רק על השדה google.maps.addressvalidation.v1.ValidationResult.usps_data של google.maps.addressvalidation.v1.ValidationResult. הערה: לבקשות עם אישור USPS CASS לכתובות בפוארטו ריקו, יש לספק google.type.PostalAddress.region_code מהaddress כ-'PR', או google.type.PostalAddress.administrative_area מהaddress שיש לספק כ'פוארטו ריקו' (לא תלוי-רישיות) או PR.

מומלץ להשתמש ברכיב address שמחושב כרכיב. לחלופין, מומלץ לציין לפחות שני רכיבי google.type.PostalAddress.address_lines שבהם השורה הראשונה מכילה את מספר הרחוב והשם והשורה השנייה כוללת את העיר, המדינה והמיקוד.
languageOptions

object (LanguageOptions)

זה שינוי אופציונלי. תצוגה מקדימה: התכונה הזו נמצאת ב'תצוגה מקדימה' (pre-GA). יכול להיות שהתמיכה במוצרים ובתכונות טרום-GA תהיה מוגבלת, ויכול להיות ששינויים במוצרים ובתכונות טרום-GA לא יתאימו לגרסאות אחרות של טרום-GA. מוצרים במצב טרום-זמינות לכלל המשתמשים כפופים לתנאים הספציפיים לשירות של הפלטפורמה של מפות Google. מידע נוסף זמין במאמר תיאורים של שלבי ההשקה.

הפעלת ה-API לאימות כתובת כדי לכלול מידע נוסף בתשובה.
sessionToken

string

זה שינוי אופציונלי. מחרוזת המזהה פעילות של השלמה אוטומטית למטרות חיוב. חייב להיות מחרוזת base64 בטוחה לכתובת URL ולשם קובץ עם 36 תווי ASCII לכל היותר. אחרת, מוחזרת שגיאת INVALID_ARGUMENT.

הסשן מתחיל כשהמשתמש מבצע שאילתה של השלמה אוטומטית, ומסתיים כשהוא בוחר מקום ומתבצעת קריאה לפרטי מקום או לאימות כתובת. כל סשן יכול לכלול מספר שאילתות של השלמה אוטומטית, ולאחר מכן בקשה אחת לאימות פרטי מקום או בקשה לאימות כתובת. פרטי הכניסה שבהם נעשה שימוש לכל בקשה בסשן חייבים להיות שייכים לאותו פרויקט במסוף Google Cloud. אחרי שסשן מסתיים, האסימון כבר לא בתוקף. האפליקציה חייבת ליצור אסימון חדש לכל סשן. אם לא מזינים את הפרמטר sessionToken, או אם משתמשים שוב באסימון סשן, הסשן יחויב כאילו לא סופק אסימון סשן (כל בקשה מחויבת בנפרד).

הערה: ניתן להשתמש באימות כתובות רק בסשנים עם API של השלמה אוטומטית (חדש) ולא עם השלמה אוטומטית API. מידע נוסף זמין בכתובת https://developers.google.com/maps/documentation/places/web-service/session-pricing.

גוף התשובה

תשובה לבקשה לאימות כתובת.

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "result": {
    object (ValidationResult)
  },
  "responseId": string
}
שדות
result

object (ValidationResult)

התוצאה של אימות הכתובת.
responseId

string

המזהה הייחודי (UUID) שמזהה את התגובה הזו. אם צריך לאמת מחדש את הכתובת, מזהה ייחודי אוניברסלי (UUID) חייב להצטרף לבקשה החדשה.

PostalAddress

מייצג כתובת למשלוח דואר, למשל עבור כתובות למשלוח דואר או תשלומים. אם תספקו כתובת למשלוח דואר, שירות הדואר יכול לשלוח פריטים לעסק שלכם, P.O. Box או דומה. הוא לא נועד לבנות מודלים של מיקומים גיאוגרפיים (כבישים, ערים, הרים).

בשימוש אופייני, כתובת תיווצר על ידי קלט של משתמשים או על ידי ייבוא נתונים קיימים, בהתאם לסוג התהליך.

עצות לגבי קלט / עריכה של כתובת: - השתמשו בווידג'ט כתובת שמוכן ללוקליזציה כמו 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.
regionCode

string

זה שינוי אופציונלי. קוד האזור במאגר CLDR של המדינה או האזור של הכתובת. פרטים נוספים זמינים בכתובת https://cldr.unicode.org/ ובכתובת https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html. דוגמה: 'CH' עבור שווייץ. אם לא תציינו את קידומת האזור, המערכת תסיק אותו מהכתובת בכתובת. לקבלת הביצועים הכי טובים, מומלץ לכלול את קוד האזור אם הוא ידוע לך. אזורים לא עקביים או חוזרים על עצמם עלולים להוביל לביצועים נמוכים. לדוגמה, אם addressLines כבר כולל את האזור, אין לספק שוב את קוד האזור בשדה הזה. מידע על אזורים נתמכים זמין בדף שאלות נפוצות.
languageCode

string

קוד השפה בכתובת הקלט שמור לשימושים עתידיים והמערכת מתעלמת ממנו היום. ה-API מחזיר את הכתובת בשפה המתאימה למיקום של הכתובת.
postalCode

string

זה שינוי אופציונלי. המיקוד של הכתובת. לא בכל המדינות נעשה שימוש במספרי המיקוד או שחובה לציין אותם, אבל במקומות שבהם נעשה שימוש בתכונה הזו, המערכת עשויה להפעיל אימות נוסף בחלקים אחרים של הכתובת (למשל, אימות מדינה או מיקוד בארה"ב).
sortingCode

string

זה שינוי אופציונלי. קוד מיון נוסף ספציפי למדינה. ברוב האזורים לא נעשה שימוש בהרשאה הזו. במקומות שבהם משתמשים בו, הערך הוא מחרוזת כמו CEDEX, ואחריו מספר (למשל CEDEX 7) או מספר בלבד, שמייצג את 'קוד המגזר'. (ג'מייקה), "אינדיקטור אזור למשלוחים" (מלאווי) או "אינדיקטור של סניף דואר" (למשל, חוף השנהב).
administrativeArea

string

זה שינוי אופציונלי. חלוקת המשנה האדמיניסטרטיבית הגבוהה ביותר שמשמשת לכתובות דואר של מדינה או אזור. לדוגמה, סוג המשנה יכול להיות מדינה, מחוז, אובלסט או מחוז. באופן ספציפי, בספרד מדובר במחוז ולא בקהילה האוטונומית (למשל, "ברצלונה" ולא "קטלוניה"). במדינות רבות לא נעשה שימוש באזור מנהלי בכתובות דואר. לדוגמה בשווייץ, אין למלא את השדה הזה.
locality

string

זה שינוי אופציונלי. מתייחס באופן כללי לחלק של העיר או העיר בכתובת. דוגמאות: עיר בארה"ב, קהילת IT, עיר דואר בבריטניה. באזורים בעולם שבהם רשויות מוניציפאליות לא מוגדרות היטב או שלא מתאימות למבנה הזה בצורה טובה, השאירו את הרשות המוניציפאלית ריקה והשתמשו בקווי כתובת.
sublocality

string

זה שינוי אופציונלי. אזור המשנה של הכתובת. לדוגמה, המאפיינים יכולים להיות שכונות, רובעים או מחוזות.
addressLines[]

string

חובה. שורות כתובת לא מובנות, שמתארות את הרמות הנמוכות יותר של כתובת.

מכיוון שערכים ב-addressLines לא כוללים פרטי סוג ולפעמים הם עשויים להכיל מספר ערכים בשדה יחיד (למשל "Austin, TX"), חשוב שסדר השורות יהיה ברור. סדר שורות הכתובת צריך להיות "סדר מעטפה" עבור המדינה/האזור של הכתובת.

הייצוג המבני המינימלי המותר של כתובת מורכב מכל המידע שמוצב בaddressLines. אם לא צוין regionCode, המערכת מסיקה את האזור משורות הכתובת.

יצירת כתובת שמכילה רק את addressLines, ולאחר מכן קידוד גיאוגרפי הוא הדרך המומלצת לטיפול בכתובות לא מובנות לחלוטין (בניגוד לניחוש אילו חלקים של הכתובת צריכים להיות יישובים או אזורים מנהליים).
recipients[]

string

יש להימנע מהגדרת השדה הזה. ה-API לאימות כתובת לא משתמש בו כרגע. בשלב הזה ה-API לא ידחה בקשות עם השדה הזה, אבל המידע יימחק ולא יוחזר בתשובה.
organization

string

יש להימנע מהגדרת השדה הזה. ה-API לאימות כתובת לא משתמש בו כרגע. בשלב הזה ה-API לא ידחה בקשות עם השדה הזה, אבל המידע יימחק ולא יוחזר בתשובה.

LanguageOptions

תצוגה מקדימה: התכונה הזו נמצאת ב'תצוגה מקדימה' (pre-GA). יכול להיות שהתמיכה במוצרים ובתכונות טרום-GA תהיה מוגבלת, ויכול להיות ששינויים במוצרים ובתכונות טרום-GA לא יתאימו לגרסאות אחרות של טרום-GA. מוצרים במצב טרום-זמינות לכלל המשתמשים כפופים לתנאים הספציפיים לשירות של הפלטפורמה של מפות Google. מידע נוסף זמין במאמר תיאורים של שלבי ההשקה.

הפעלת ה-API לאימות כתובת כדי לכלול מידע נוסף בתשובה.

ייצוג JSON 
{
  "returnEnglishLatinAddress": boolean
}
שדות
returnEnglishLatinAddress

boolean

תצוגה מקדימה: החזרת google.maps.addressvalidation.v1.Address באנגלית. אתה יכול לראות עוד פרטים בכתובת google.maps.addressvalidation.v1.ValidationResult.english_latin_address.

ValidationResult

התוצאה של אימות כתובת.

ייצוג JSON 
{
  "verdict": {
    object (Verdict)
  },
  "address": {
    object (Address)
  },
  "geocode": {
    object (Geocode)
  },
  "metadata": {
    object (AddressMetadata)
  },
  "uspsData": {
    object (UspsData)
  },
  "englishLatinAddress": {
    object (Address)
  }
}
שדות
verdict

object (Verdict)

דגלים לגבי תוצאה כוללת
address

object (Address)

מידע על הכתובת עצמה, ולא על הקוד הגיאוגרפי.
geocode

object (Geocode)

מידע על המיקום והמקום שאליו הכתובת המקודדת.
metadata

object (AddressMetadata)

מידע אחר שרלוונטי למסירה. לא מובטח שהשדה metadata יאוכלס במלואו בכל כתובת שנשלחת ל-API לאימות כתובת.
uspsData

object (UspsData)

סימוני מסירה נוספים סופקו על ידי USPS. סופק רק באזור US ו-PR.
englishLatinAddress

object (Address)

תצוגה מקדימה: התכונה הזו נמצאת ב'תצוגה מקדימה' (pre-GA). יכול להיות שהתמיכה במוצרים ובתכונות טרום-GA תהיה מוגבלת, ויכול להיות ששינויים במוצרים ובתכונות טרום-GA לא יתאימו לגרסאות אחרות של טרום-GA. מוצרים במצב טרום-זמינות לכלל המשתמשים כפופים לתנאים הספציפיים לשירות של הפלטפורמה של מפות Google. מידע נוסף זמין במאמר תיאורים של שלבי ההשקה.

הכתובת תורגמה לאנגלית.

אי אפשר לעשות שימוש חוזר בכתובות מתורגמות כקלט 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
}
שדות
inputGranularity

enum (Granularity)

רמת הפירוט של הכתובת לקלט. התוצאה היא ניתוח של כתובת הקלט והיא לא מספקת אותות אימות. מידע לגבי אותות אימות מופיע בקטע validationGranularity שבהמשך.

לדוגמה, אם הכתובת שהוזן כוללת מספר דירה ספציפי, הערך של inputGranularity כאן יהיה SUB_PREMISE. אם אנחנו לא יכולים להתאים את מספר הדירה במסדי הנתונים או שמספר הדירה לא תקין, הערך של validationGranularity ככל הנראה יהיה PREMISE ומטה.
validationGranularity

enum (Granularity)

רמת הפירוט שבה ה-API יכול לאמת באופן מלא את הכתובת. לדוגמה, validationGranularity של PREMISE מציין את כל רכיבי הכתובת ברמה של PREMISE או יותר שניתן לאמת אותם בהערכה גסה.

תוצאת האימות של רכיב לכתובת מופיעה ב-google.maps.addressvalidation.v1.Address.address_components.
geocodeGranularity

enum (Granularity)

מידע על רמת הפירוט של geocode. אפשר להבין את זה בתור המשמעות הסמנטית של מידת הגסות או הנעימות של המיקום הגיאוגרפי של המיקום.

זה יכול להיות שונה מהמדד validationGranularity שמוצג למעלה מדי פעם. לדוגמה, מסד הנתונים עשוי לתעד את קיומו של מספר דירה, אבל לא את המיקום המדויק של הדירה בתוך מתחם דירות גדול. במקרה הזה, הערך של validationGranularity יהיה SUB_PREMISE אבל הערך של geocodeGranularity יהיה PREMISE.
addressComplete

boolean

הכתובת נחשבת מלאה אם אין אסימונים שלא טופלו, אין רכיבי כתובת לא צפויים או חסרים. אם המדיניות לא מוגדרת, הערך הוא false. לפרטים נוספים, אפשר לעיין בשדות missingComponentTypes, unresolvedTokens או unexpected.
hasUnconfirmedComponents

boolean

לא ניתן לסווג או לאמת לפחות רכיב כתובת אחד. לפרטים נוספים, יש לעיין בכתובת google.maps.addressvalidation.v1.Address.address_components.
hasInferredComponents

boolean

המערכת הסיקה (נוסף) לפחות רכיב כתובת אחד שלא נכלל בקלט. לפרטים נוספים, אפשר לעיין ב-google.maps.addressvalidation.v1.Address.address_components.
hasReplacedComponents

boolean

הוחלף לפחות רכיב כתובת אחד. פרטים נוספים מופיעים בכתובת google.maps.addressvalidation.v1.Address.address_components.

רמת פירוט

פירוט הנתונים השונים שיכולים להיות לכתובת או לקואורדינטות. כשהם מציינים את רמת הפירוט של כתובת, הערכים האלה מציינים את רמת הפירוט של הכתובת לזיהוי יעד למשלוח דואר. לדוגמה, כתובת כמו "123 Main Street, Redwood City, CA, 94061" מזהה PREMISE, במקום משהו כמו "Redwood City, CA, 94061" מזהה LOCALITY. עם זאת, אם אין באפשרותנו למצוא קואורדינטות של "הרחוב הראשי 123" ברדווד סיטי, הקוד הגיאוגרפי שמוחזר עשוי להיות ברמת פירוט של LOCALITY למרות שהכתובת מפורטת יותר.

טיפוסים בני מנייה (enum)
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'] יכול להיות קלט כמו "Boulder, Colorado, 80301, USA". רשימה של הסוגים האפשריים מופיעה כאן.
unconfirmedComponentTypes[]

string

סוגי הרכיבים שקיימים בaddressComponents אבל לא ניתן היה לאשר שהם נכונים. מטעמי נוחות: התוכן שלו מקביל לאיטרציה באמצעות addressComponents כדי למצוא את הסוגים של כל הרכיבים שבהם הערך של confirmationLevel אינו CONFIRMED או שהדגל inferred לא מוגדר לערך true. רשימה של הסוגים האפשריים מופיעה כאן.
unresolvedTokens[]

string

כל האסימונים בקלט שלא ניתן לפענח. זה יכול להיות קלט שלא זוהה כחלק מכתובת חוקית (לדוגמה, בקלט כמו "123235253253 Main St, San Francisco, CA, 94105". האסימונים שלא זוהו עשויים להיראות כמו ["123235253253"] כי זה לא נראה כמו מספר בית חוקי.

AddressComponent

מייצג רכיב כתובת, כמו רחוב, עיר או מדינה.

ייצוג JSON 
{
  "componentName": {
    object (ComponentName)
  },
  "componentType": string,
  "confirmationLevel": enum (ConfirmationLevel),
  "inferred": boolean,
  "spellCorrected": boolean,
  "replaced": boolean,
  "unexpected": boolean
}
שדות
componentName

object (ComponentName)

השם של הרכיב הזה.
componentType

string

הסוג של רכיב הכתובת. ראו טבלה 2: סוגים נוספים שהוחזרו על ידי שירות 'מקומות' לרשימת הסוגים האפשריים.
confirmationLevel

enum (ConfirmationLevel)

מציין את רמת הוודאות שיש לנו לגבי כך שהרכיב נכון.
inferred

boolean

מציין שהרכיב לא היה חלק מהקלט, אבל הסקנו אותו לגבי מיקום הכתובת ואנחנו מאמינים שצריך לספק אותו כדי לציין כתובת מלאה.
spellCorrected

boolean

מציין תיקון לשגיאת איות בשם הרכיב. ה-API לא תמיד מסמן שינויים מווריאנט איות אחד לאחר, למשל כשמשנים את ה'מרכז'. ל-"center" [מרכז]. הוא גם לא תמיד מסמן שגיאות איות נפוצות, כמו למשל שינוי של "Amphiteater Pkwy" (אמפיתיאטרון Pkwy) ועד Amphitheatre Pkwy.
replaced

boolean

מציין ששם הרכיב הוחלף בשם אחר לגמרי. לדוגמה, מיקוד שגוי הוחלף במיקוד הנכון עבור הכתובת. זה לא שינוי קוסמטי, רכיב הקלט הוחלף לרכיב אחר.
unexpected

boolean

מציין רכיב כתובת שלא צפוי להופיע בכתובת למשלוח דואר באזור הנתון. שמרנו אותו רק בגלל שהוא היה חלק מהקלט.

ComponentName

wrapper לשם הרכיב.

ייצוג JSON 
{
  "text": string,
  "languageCode": string
}
שדות
text

string

הטקסט של השם. לדוגמה, "השדרה החמישית" לשם רחוב או '1253' למספר בית.
languageCode

string

קוד השפה BCP-47. המידע הזה לא יופיע אם שם הרכיב לא משויך לשפה, כמו מספר בית.

ConfirmationLevel

הערכים האפשריים השונים של רמות האישור.

טיפוסים בני מנייה (enum)
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)

המיקום הקואורדינטות של הקלט.

עדיף להשתמש במזהי מקומות על פני כתובות, קואורדינטות של קווי אורך ורוחב או קודי OLC. שימוש בקואורדינטות בעת ניתוב או חישוב מסלול נסיעה יגרום תמיד להצמדה של הנקודה לכביש הקרוב ביותר לקואורדינטות האלה. זה לא יכול להיות כביש שיוביל במהירות או בבטחה ליעד, ולא יכול להיות ליד נקודת גישה לנכס. בנוסף, כשהגדרת המיקום היא הפוכה, לא מובטח שהכתובת שהוחזרה תתאים לכתובת המקורית.
plusCode

object (PlusCode)

ה-Plus Code של location.
bounds

object (Viewport)

גבולות המקום המקדים.
featureSizeMeters

number

גודל המקום עם הקואורדינטות, במטרים. זה מדד נוסף של גסות המיקום הגיאוגרפי שמזינים בו את הקוד, אבל בגודלו הפיזי ולא במשמעות הסמנטית.
placeId

string

ה-PlaceID של המקום שאליו מתבצעת הקידוד הגיאוגרפי של הקלט הזה.

מידע נוסף על מזהי מקומות זמין כאן.
placeTypes[]

string

סוגי המקומות שהקלט ביצע להם קידוד גיאוגרפי. לדוגמה, ['locality', 'political']. רשימת הסוגים המלאה זמינה כאן.

LatLng

אובייקט שמייצג צמד של קו רוחב/קו אורך. הערך הזה מבוטאת כצמד של כפולים כדי לייצג מעלות קו רוחב ומעלות קו אורך. האובייקט חייב לעמוד בדרישות של תקן WGS84, אלא אם צוין אחרת. הערכים חייבים להיות בטווחים מנורמלים.

ייצוג JSON 
{
  "latitude": number,
  "longitude": number
}
שדות
latitude

number

קו הרוחב במעלות. הוא חייב להיות בטווח [-90.0, +90.0].
longitude

number

קו האורך במעלות. הוא חייב להיות בטווח [-180.0, +180.0].

PlusCode

Plus Code (http://plus.codes) הוא הפניה למיקום בשני פורמטים: קוד גלובלי שמגדיר 14mx14m (1/8, 000 במעלה) או מלבן קטן יותר, וקוד מורכב שמחליף את הקידומת במיקום של הפניה.

ייצוג JSON 
{
  "globalCode": string,
  "compoundCode": string
}
שדות
globalCode

string

הקוד הגלובלי (מלא) של המקום, כמו '9FWM33GV+HQ', שמייצג שטח של 1/8,000 על 1/8,000 מעלות (כ-14 על 14 מטרים).
compoundCode

string

קוד מורכב של מקום, למשל '33GV+HQ, Rammber, נורבגיה', שמכיל את הסיומת של הקוד הגלובלי ומחליף את הקידומת בשם בפורמט של ישות עזר.

אזור התצוגה

אזור תצוגה של קו רוחב, מיוצג בשתי אלכסון מול low ו-high נקודות. אזור תצוגה נחשב לאזור סגור, כלומר הוא כולל את התחום שלו. גבולות הרוחב חייבים להיות בטווח של -90 עד 90 מעלות כולל, וגבולות קו האורך חייבים לנוע בין -180 ל-180 מעלות, כולל. מקרים שונים כוללים:

  • אם low = high, אזור התצוגה מורכב מנקודה אחת בלבד.

  • אם low.longitude > high.longitude, טווח קו האורך הפוך (אזור התצוגה חוצה את קו האורך 180 מעלות).

  • אם low.longitude = -180 מעלות ו-high.longitude = 180 מעלות, אזור התצוגה כולל את כל קווי האורך

  • אם low.longitude = 180 מעלות ו-high.longitude = 180 מעלות, טווח קו האורך ריק.

  • אם low.latitude > high.latitude, טווח קו הרוחב ריק.

צריך לאכלס גם את low וגם את high, והתיבה המיוצגת לא יכולה להיות ריקה (כפי שצוין בהגדרות שלמעלה). אזור תצוגה ריק יגרום לשגיאה.

לדוגמה, אזור התצוגה הזה כולל את כל העיר תל אביב:

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

ייצוג JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
שדות
low

object (LatLng)

חובה. הנקודה הנמוכה של אזור התצוגה.
high

object (LatLng)

חובה. הנקודה הגבוהה של אזור התצוגה.

AddressMetadata

המטא-נתונים של הכתובת. לא מובטח שהשדה metadata יאוכלס במלואו בכל כתובת שנשלחת ל-API לאימות כתובת.

ייצוג JSON 
{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}
שדות
business

boolean

מציין שזו כתובת של עסק. אם המדיניות לא מוגדרת, הערך מציין שהערך לא ידוע.
poBox

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
}
שדות
standardizedAddress

object (UspsAddress)

כתובת סטנדרטית של USPS.
deliveryPointCode

string

קוד נקודת מסירה בן 2 ספרות
deliveryPointCheckDigit

string

ספרת הביקורת של נקודת המסירה. המספר הזה מתווסף לסוף ה-delivery_point_barcode עבור דואר שנסרק באופן מכני. חיבור כל הספרות של ה-delivery_point_barcode, deliveryPointCheckDigit, המיקוד וה-ZIP+4 אמור להניב מספר שמתחלק ב-10.
dpvConfirmation

string

הערכים האפשריים לאישור DPV. מחזירה תו יחיד או לא מחזירה ערך.

  • N: נכשל אישור ה-DPV של פרטי המספר הראשי והפרטים המשניים.
  • D: הכתובת אושרה DPV עבור המספר הראשי בלבד, ופרטי המספר המשני היו חסרים.
  • S: הכתובת אושרה DPV עבור המספר הראשי בלבד, ופרטי המספר המשני קיימים אבל לא אושרו.
  • Y: הכתובת אושרה ל-DPV למספר הראשי ולמספרים משניים.
  • ריקה: אם התשובה לא מכילה ערך dpvConfirmation, הכתובת לא נשלחה לאישור DPV.
dpvFootnote

string

הערות השוליים מאימות נקודת המסירה. ניתן להצמיד כמה הערות שוליים באותה מחרוזת.

  • AA: כתובת הקלט תואמת לקובץ ה-ZIP+4
  • A1: כתובת הקלט לא הותאמה לקובץ ZIP+4
  • BB: תואם ל-DPV (כל הרכיבים)
  • CC: אין התאמה למספר משני ולא נדרש
  • C1: אין התאמה למספר משני אבל נדרש
  • N1: בכתובת של רב קומות חסר מספר משני
  • M1: חסר מספר ראשי
  • M3: מספר ראשי לא חוקי
  • P1: חסר מספר הזמנת רכש, RR או תיבת מרכז העזרה של הכתובת
  • P3: מספר לא חוקי של כתובת הזמנת רכש, RR או תיבת מרכז העזרה
  • F1: כתובת הקלט הותאמה לכתובת צבאית
  • G1: כתובת הקלט שהוזנה לכתובת כללית למשלוח
  • U1: כתובת הקלט תואמת למיקוד ייחודי
  • PB: כתובת הקלט הותאמה לרשומת PBSA
  • RR: כתובת מאושרת של DPV עם פרטי PMB
  • R1: כתובת מאושרת של DPV ללא פרטי PMB
  • R7: רשומת R777 או רשומת R779 של ספק הסלולר
  • IA: זוהתה כתובת מאושרת
  • TA: המספר הראשי תואם על ידי השמטת אלפא בסוף
dpvCmra

string

מאפיין זה מציין אם הכתובת היא CMRA (סוכנות לקבלת דואר מסחרי) – עסק פרטי שמקבל דואר עבור לקוחות. מחזירה תו יחיד.

  • Y: הכתובת היא CMRA
  • N: הכתובת אינה CMRA
dpvVacant

string

המקום הזה ריק? מחזירה תו יחיד.

  • Y: הכתובת ריקה
  • N: הכתובת לא ריקה
dpvNoStat

string

האם זו כתובת קבועה או כתובת פעילה? אין כתובות סטטיות הן כתובות שלא מאוכלסות באופן קבוע או כתובות שלא ניתנות שירות על ידי USPS. מחזירה תו יחיד.

  • Y: הכתובת לא פעילה
  • N: הכתובת פעילה
dpvNoStatReasonCode

integer

מציין את הסוג NoStat. הפונקציה מחזירה את קוד הסיבה בפורמט int.

  • 1: IDA (כתובת מסירה פנימית) – כתובות שלא מקבלות אימייל ישירות מה-USPS אבל נמסרות לכתובת שנותנת שירות.
  • 2: תקליטורי CDS – כתובות שעדיין לא ניתן להעביר. לדוגמה, חלוקת משנה חדשה שבה הוגדרו חלקות ומספרים ראשיים, אבל עדיין לא קיים מבנה לתפוסה.
  • 3: התנגשות – כתובות שלא בוצע אישור של DPV בפועל.
  • 4: CMZ (מכללה, צבא וסוגים אחרים) – רשומות ZIP + 4 רשומות USPS שילבו בנתונים.
  • 5: רגילה – מציין כתובות שלא מקבלות משלוח, והכתובות לא נספרות כמשלוחים אפשריים.
  • 6: שדה חובה משני – הכתובת מחייבת מידע משני.
dpvDrop

string

דגל מציין שהאימייל נשלח לנמען אחד באתר מסוים. מחזירה תו יחיד.

  • Y: הדואר נמסר לנמען אחד באתר.
  • N: הדואר לא נמסר לנמען אחד באתר.
dpvThrowback

string

מציין שהדואר לא נמסר לכתובת. מחזירה תו יחיד.

  • Y: הדואר לא נמסר לכתובת.
  • N: הדואר נמסר לכתובת.
dpvNonDeliveryDays

string

דגל מציין כי שליחת הדואר לא מתבצעת בכל יום בשבוע. מחזירה תו יחיד.

  • Y: שליחת הדואר לא מתבצעת בכל יום בשבוע.
  • N: אין אינדיקציה לכך ששליחת הדואר לא מתבצעת בכל יום בשבוע.
dpvNonDeliveryDaysValues

integer

מספר שלם שמזהה ימים שלא נמסרו. אפשר לבדוק את הנושא באמצעות סימונים בביט: 0x40 עד יום ראשון הוא יום ללא מסירה 0x20 – יום שני הוא יום אי-מסירה 0x10 – יום שלישי הוא יום אי-מסירה בין השעות 0x08 – יום רביעי הוא יום אי-מסירה 0x04 עד חמישי הוא יום ללא מסירה 0x02 עד שישי עד שבת, לא מסירה ביום 0x0
dpvNoSecureLocation

string

הדגל מציין שהדלת נגישה, אבל החבילה לא תושאר בגלל בעיות אבטחה. מחזירה תו יחיד.

  • Y: החבילה לא תושאר בגלל בעיות אבטחה.
  • N: אין אינדיקציה שהחבילה לא תעזוב עקב בעיות אבטחה.
dpvPbsa

string

מציין שהכתובת הותאמה לרשומת PBSA. מחזירה תו יחיד.

  • Y: הכתובת הותאמה לרשומת PBSA.
  • N: הכתובת לא הותאמה לרשומת PBSA.
dpvDoorNotAccessible

string

הדגל מציין כתובות שבהן USPS לא יכול לבקש דפי נחיתה בדלת כדי למסור דואר. מחזירה תו יחיד.

  • Y: אין גישה לדלת.
  • N: אין סימן שאי אפשר לגשת לדלת.
dpvEnhancedDeliveryCode

string

מציין שיש יותר מקוד החזרה אחד של DPV חוקי עבור הכתובת. מחזירה תו יחיד.

  • Y: הכתובת אושרה ל-DPV למספר הראשי ולמספרים משניים.
  • N: נכשל אישור ה-DPV של פרטי המספר הראשי והפרטים המשניים.
  • S: הכתובת אושרה כ-DPV עבור המספר הראשי בלבד, ופרטי המספר המשני היו קיימים אך לא אושרו, או שהושמטה אלפא אחת בסוף המספר הראשי כדי לבצע התאמת DPV ונדרש מידע משני.
  • D: הכתובת אושרה DPV עבור המספר הראשי בלבד, ופרטי המספר המשני היו חסרים.
  • R: הכתובת אושרה אבל הוקצתה לנתיב הפנטום R777 ו-R779 ולא סופקה משלוח ב-USPS.
carrierRoute

string

קוד המסלול של הספק. קוד בן ארבעה תווים שמורכב מקידומת של אות אחת ומציין מסלול בן שלוש ספרות.

קידומות:

  • C: מסלול של חברת התובלה (או מסלול עירוני)
  • R: מסלול כפרי
  • H: מסלול עם חוזה בכביש מהיר
  • B: אזור של תא דואר
  • G: יחידת משלוח כללית
carrierRouteIndicator

string

אינדיקטור למיון של קצב המסלול של חברת התובלה.
ewsNoMatch

boolean

ניתן להתאים את הכתובת למשלוח, אבל בקובץ ה-EWS מצוין שהתאמה מדויקת תהיה זמינה בקרוב.
postOfficeCity

string

העיר הראשית של סניף הדואר.
postOfficeState

string

המדינה הראשית של סניף הדואר.
abbreviatedCity

string

קיצור של 'עיר'.
fipsCountyCode

string

קוד מחוז FIPS.
county

string

שם המחוז.
elotNumber

string

מספר משופר של קו נסיעה (eLOT).
elotFlag

string

eLOT דגל עולה/יורד (A/D).
poBoxOnlyPostalCode

boolean

המיקוד של תא דואר בלבד.
pmbDesignator

string

מגדיר יחידות PMB (תיבת דואר פרטית).
pmbNumber

string

מספר PMB (תיבת דואר פרטית)
addressRecordType

string

הסוג של רשומת הכתובת שתואמת לכתובת הקלט.

  • F: FIRM. זוהי התאמה לרשומת חברה, שהיא רמת ההתאמה הטובה ביותר שזמינה לכתובת מסוימת.
  • G: משלוח כללי. זוהי התאמה לרשומת הצגה כללית (General Delivery).
  • H: מיקום / דירה. זוהי התאמה לרשומה של בניין או דירה.
  • P: תיבת דואר לפרסום. פריט זה תואם לתא דואר.
  • R: RURAL ROUTE או highWAY CONTRACT: זוהי התאמה לרשומה של מסלול כפרי או לרשומה של חוזה בכביש מהיר, שלשניהם עשויים להיות טווחים משויכים של מספרי Box.
  • S: רשומת STREET: זוהי התאמה לרשומת רחוב שמכילה טווח מספרים ראשי חוקי.
defaultAddress

boolean

אינדיקטור שמציין שקיימת כתובת ברירת מחדל, אבל קיימות כתובות ספציפיות יותר.
errorMessage

string

הודעת שגיאה לאחזור נתונים של USPS. השדה הזה מאוכלס כשעיבוד USPS מושעה עקב זיהוי של כתובות שנוצרו באופן מלאכותי.

יכול להיות ששדות הנתונים של USPS לא יאוכלסו כשהשגיאה הזו קיימת.
cassProcessed

boolean

אינדיקטור שמציין שהבקשה עברה עיבוד CASS.

UspsAddress

ייצוג של כתובת בארה"ב ב-USPS.

ייצוג JSON 
{
  "firstAddressLine": string,
  "firm": string,
  "secondAddressLine": string,
  "urbanization": string,
  "cityStateZipAddressLine": string,
  "city": string,
  "state": string,
  "zipCode": string,
  "zipCodeExtension": string
}
שדות
firstAddressLine

string

שורת כתובת ראשונה.
firm

string

שם החברה.
secondAddressLine

string

שורת כתובת שנייה.
urbanization

string

שם העיור.
cityStateZipAddressLine

string

עיר + מדינה + מיקוד.
city

string

שם העיר.
state

string

קוד מדינה בן 2 אותיות.
zipCode

string

מיקוד, למשל 10009.
zipCodeExtension

string

סיומת מיקוד בן 4 ספרות, למשל: 5023.