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 בכתובת הקלט שמור לשימושים עתידיים, והמערכת מתעלמת ממנו היום. תוצאת הכתובת המאומתת תאוכלס על סמך השפה המועדפת עבור הכתובת הנתונה, כפי שהיא תזוהה על ידי המערכת.

ה-Address Validation 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. מוצרים במצב טרום-GA מכוסים על ידי התנאים הספציפיים לשירות בפלטפורמה של מפות Google. מידע נוסף זמין בתיאורים של שלבי ההשקה.

מאפשר ל-Address Validation 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

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

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

ייעוץ לגבי קלט או עריכה של כתובות: - משתמשים בווידג'ט כתובת שמוכן להתאמה לשוק המקומי, כמו 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, עיירה בבריטניה. באזורים בעולם שבהם הרשויות המוניציפאליות אינן מוגדרות היטב או שאינן מתאימות למבנה זה, יש להשאיר את הרשות המוניציפאלית ריקה ולהשתמש בערכי addressLines.
sublocality

string

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

string

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

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

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

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

string

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

string

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

LanguageOptions

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

מאפשר ל-Address Validation 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 יאוכלס במלואו לכל כתובת שנשלחת ל-Address Validation API.
uspsData

object (UspsData)

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

object (Address)

תצוגה מקדימה: התכונה הזו נמצאת בתצוגה המקדימה (pre-GA). התמיכה במוצרים ובתכונות טרום-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 יכול validate את הכתובת במלואה. לדוגמה, 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.

רמת פירוט

רמות הפירוט השונות שיכולות להיות לכתובת או לקואורדינטות. כאשר הם משמשים לציון רמת פירוט של כתובת, הערכים האלה מציינים את רמת הפירוט של הכתובת שמזהה יעד למשלוח. לדוגמה, כתובת כמו 'רחוב הרצל 12, תל אביב, ישראל, 10307' מזהה PREMISE, ומילים כמו "Redwood City, CA, 94061" הן LOCALITY. עם זאת, אם לא נצליח למצוא קואורדינטות של "רחוב ראשי 123" ב-Redwood City, הקואורדינטות יכולות להיות ברמת פירוט של 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
  ]
}
שדות
formattedAddress

string

הכתובת אחרי העיבוד, בפורמט של כתובת עם שורה אחת לפי כללי הפורמט של הכתובת באזור שבו הכתובת ממוקמת.
postalAddress

object (PostalAddress)

הכתובת שעברה עיבוד מיוצגת ככתובת למשלוח דואר.
addressComponents[]

object (AddressComponent)

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

רכיבי הכתובת אינם מסודרים בצורה מסוימת. אין להניח הנחות לגבי סדר רכיבי הכתובת ברשימה.
missingComponentTypes[]

string

סוגי הרכיבים שהיו צפויים להופיע בכתובת למשלוח דואר בפורמט תקין, אך לא נמצאו בקלט וגם לא ניתן היה להסיק אותם. רכיבים מהסוג הזה לא קיימים ב-formattedAddress, ב-postalAddress או ב-addressComponents. לדוגמה: ['street_number', 'route'] לקלט כמו "Boolder, Colorado, 80301, USA". רשימת הסוגים האפשריים זמינה כאן.
unconfirmedComponentTypes[]

string

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

string

אסימונים בקלט שלא ניתן לפענח. יכול להיות שמדובר בקלט שלא זוהה כחלק תקין של כתובת (לדוגמה בקלט כמו " 123235253253 ראשי תל אביב, תל אביב, ישראל, 64340", האסימונים שלא זוהו עשויים להיראות כך: ["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 לא תמיד מסמן שינויים בין וריאנטים של איותים, למשל שינויים מ-"centre" ל-"center". כמו כן, התכונה לא תמיד מסמנת שגיאות כתיב נפוצות, למשל כאשר משנים את הביטוי " Amphitheatre Pkwy" (אמפיתאטרון Pkwy) ל-"Amphitheatre Pkwy".
replaced

boolean

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

boolean

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

ComponentName

wrapper עבור שם הרכיב.

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

string

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

string

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

ConfirmationLevel

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

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

המיקום המקודד גיאוגרפי של הקלט.

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

object (PlusCode)

ה-OLC שתואם ל-location.
bounds

object (Viewport)

גבולות המקום שעבר קואורדינטות.
featureSizeMeters

number

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

string

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

מידע נוסף על מזהי מקומות זמין כאן.
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/8000 מעלות) או מלבן קטן יותר, וקוד מורכב שמחליף את הקידומת במיקום הפניה.

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

string

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

string

קוד מורכב של מקום, כמו "33GV+HQ, Ramברג, נורווגיה", שמכיל את הסיומת של הקוד הגלובלי והחלפת הקידומת בשם בפורמט של ישות הפניה.

אזור התצוגה

נקודת מבט של קו אורך, מיוצגת בשתי נקודות באלכסון הנגדיות, 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 יאוכלס במלואו לכל כתובת שנשלחת ל-Address Validation API.

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

boolean

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

boolean

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

boolean

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

UspsData

נתוני USPS עבור הכתובת. לא בטוח שהשדה uspsData יאוכלס במלואו לכל כתובת בארה"ב או כתובת PR שנשלחת אל 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 – יום שישי הוא יום שבו לא נמסרה מסירה אוטומטית
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: משלוח כללי. זוהי התאמה לרשומת מסירה כללית.
  • H: בניין / דירה. זוהי התאמה לרשומה של מבנה או דירה.
  • P: POST OFFICE BOX. הקישור הזה מתאים לתיבת דואר.
  • R: RURAL ROUTE או Highway ConTRACT: זוהי התאמה לרשומה של 'מסלול כפרי' או לרשומה של חוזה בכביש מהיר, שלשניהם יכול להיות טווחים של מספרי תיבות.
  • S: רשומת רחוב: זוהי התאמה לרשומת רחוב שמכילה טווח מספרים ראשי חוקי.
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.