Method: validateAddress

אימות כתובת.

בקשת HTTP

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

כתובת ה-URL משתמשת בתחביר של Transcoding של 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 כ-'Puerto Rico' (ללא קשר לאותיות רישיות) או כ-'PR'.

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

object (LanguageOptions)

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

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

string

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

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

הערה: אפשר להשתמש באימות כתובות רק בסשנים עם Autocomplete API (חדש), ולא עם Autocomplete 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

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

string

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

string

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

string

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

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

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

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

string

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

string

מומלץ להימנע מהגדרה של השדה הזה. בשלב הזה, לא נעשה בו שימוש ב-Address Validation API. בשלב זה, ה-API לא ידחה בקשות עם השדה הזה מוגדר, אבל המידע יושלך לפח ולא יוחזר בתגובה.

LanguageOptions

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

מאפשרת ל-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)

מידע על הכתובת עצמה, בניגוד לקוד ה-Geo.
geocode

object (Geocode)

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

object (AddressMetadata)

מידע נוסף שקשור ליכולת המסירה. אין ערובה לכך שהשדה metadata יהיה מאוכלס במלואו בכל כתובת שנשלחת אל Address Validation API.
uspsData

object (UspsData)

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

object (Address)

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

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

אי אפשר להשתמש בכתובות המתורגמות שוב כקלט ל-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)

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

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

enum (Granularity)

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

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

enum (Granularity)

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

לפעמים הערך הזה עשוי להיות שונה מהערך של 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. לדוגמה, השדה postalAddress מייצג תמיד את המדינה כ-regionCode בן שתי אותיות, כמו 'IL' או 'NZ'. לעומת זאת, בשדה הזה נעשה שימוש בצורה ארוכה יותר של שם המדינה, למשל 'ארה"ב' או 'ניו זילנד'.
postalAddress

object (PostalAddress)

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

object (AddressComponent)

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

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

string

סוגי הרכיבים שהיו אמורים להופיע בכתובת למשלוח דואר בפורמט תקין, אבל לא נמצאו בקלט ולא ניתן היה להסיק אותם. לדוגמה, הערך ['street_number', 'route'] יכול להופיע כאשר מזינים 'Boulder, Colorado, 80301, USA'. כאן אפשר למצוא את רשימת הסוגים האפשריים.

הערה: יכול להיות שתראו סוג של רכיב חסר גם אם לדעתכם כבר סיפקתם את הרכיב החסר. לדוגמה, זה יכול לקרות אם הכתובת שהוזנה מכילה את שם הבניין, אבל לא את מספר הנכס. בכתובת '渋谷区渋谷３丁目　Shibuya Stream', שם הבניין 'Shibuya Stream' הוא מסוג הרכיב premise, אבל מספר הנכס חסר, ולכן השדה missingComponentTypes יכיל את הערך premise.
unconfirmedComponentTypes[]

string

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

string

אסימונים שהזנתם ולא ניתן היה לפתור אותם. יכול להיות שמדובר בקלט שלא זוהה כחלק תקין של כתובת. לדוגמה, אם מזינים 'Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US', האסימונים שלא נפתרו עשויים להיראות כך: ["Parcel", "0000123123", "&", "0000456456"].

AddressComponent

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

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

object (ComponentName)

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

string

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

enum (ConfirmationLevel)

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

boolean

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

boolean

מציין תיקון לשגיאת איות בשם הרכיב. ה-API לא תמיד מסמנים שינויים מאפשרות איות אחת לאחרת, למשל כאשר משנים את המילה 'centre' ל-'center'. בנוסף, המערכת לא תמיד מסמנת שגיאות איות נפוצות, למשל כשמשנים את הכביש 'Amphitheater Pkwy' לכביש 'Amphitheatre Pkwy'.
replaced

boolean

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

boolean

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

ComponentName

עטיפה לשם הרכיב.

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

string

טקסט השם. לדוגמה, 'שדרה 5' בשביל שם רחוב או '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)

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

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

object (PlusCode)

ה-Plus Code שתואם ל-location.
bounds

object (Viewport)

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

number

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

string

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

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

string

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

LatLng

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

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

number

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

number

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

PlusCode

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

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

string

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

string

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

אזור התצוגה

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

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

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

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

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

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

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

לדוגמה, חלון התצוגה הזה כולל את ניו יורק במלואה:

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

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

object (LatLng)

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

object (LatLng)

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

AddressMetadata

המטא-נתונים של הכתובת. אין ערובה לכך שהשדה metadata יהיה מאוכלס במלואו בכל כתובת שנשלחת אל Address Validation 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,‏ postal code ו-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: Input address PO, RR or HC box number missing
  • P3: מספר התא של כתובת ה-PO, ה-RR או ה-HC שהוזן לא תקין
  • 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 (קולג', צבא וסוגים אחרים) – רשומות של מיקוד + 4 ש-USPS שילבה בנתונים.
  • 5: רגיל – מציין כתובות שלא מתבצעים אליהן משלוחים, והכתובות האלה לא נספרות ככתובות אפשריות למשלוח.
  • 6: חובה להזין כתובת משנית – צריך להזין פרטים משניים של הכתובת.
dpvDrop

string

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

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

string

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

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

string

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

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

integer

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

string

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

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

string

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

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

string

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

  • 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: תיבת דואר. התאמה לתיבת דואר.
  • R: RURAL ROUTE או HIGHWAY CONTRACT: התאמה לרשומה של 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

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

string

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

string

תוסף של 4 ספרות למיקוד, למשל 5023.