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

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

string

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

הסשן מתחיל כשהמשתמש שולח שאילתת השלמה אוטומטית, ומסתיים כשהמשתמש בוחר מקום ומתבצעת קריאה ל-Place Details או ל-Address Validation. בכל סשן יכולות להיות כמה שאילתות של השלמה אוטומטית, ולאחר מכן בקשה אחת לקבלת פרטי מקום או לאימות כתובת. פרטי הכניסה שנעשה בהם שימוש בכל בקשה במהלך סשן חייבים להיות שייכים לאותו פרויקט במסוף 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

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

string

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

string

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

string

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

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

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

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

string

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

string

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

LanguageOptions

תצוגה מקדימה: התכונה הזו נמצאת בגרסת טרום-השקה (Preview). יכול להיות שתהיה תמיכה מוגבלת במוצרים ובתכונות במצב טרום-זמינות לכלל המשתמשים, וששינויים במוצרים ובתכונות במצב טרום-זמינות לכלל המשתמשים לא יהיו תואמים לגרסאות אחרות במצב טרום-זמינות לכלל המשתמשים. מוצרים במצב טרום-זמינות לכלל המשתמשים כפופים להתנאים הספציפיים לשירות של הפלטפורמה של מפות 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)

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

object (Geocode)

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

object (AddressMetadata)

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

object (UspsData)

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

object (Address)

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

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

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

עדיף להשתמש במזהי מקומות על פני כתובות, קואורדינטות של קווי אורך ורוחב או קודי OLC. כשמשתמשים בקואורדינטות כדי ליצור מסלול או לחשב מסלול נסיעה, הנקודה תמיד תצורף לכביש הקרוב ביותר לקואורדינטות האלה. יכול להיות שזו לא דרך שתגיע ליעד במהירות או בבטחה, ויכול להיות שהיא לא תהיה קרובה לנקודת גישה לנכס. בנוסף, כשממירים מיקום לקואורדינטות גיאוגרפיות הפוכות, אין ערובה שהכתובת שתתקבל תהיה זהה לכתובת המקורית.
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/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,‏ 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: מספר התיבה של כתובת ה-PO,‏ RR או HC חסר
  • 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: משלוח כללי. זוהי התאמה לרשומת הצגה כללית (General Delivery).
  • 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.