Package google.maps.addressvalidation.v1

אינדקס

AddressValidation

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

ProvideValidationFeedback

rpc ProvideValidationFeedback(ProvideValidationFeedbackRequest) returns (ProvideValidationFeedbackResponse)

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

rpc ValidateAddress(ValidateAddressRequest) returns (ValidateAddressResponse)

אימות כתובת.

כתובת

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

שדות
formatted_address

string

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

הערה: יכול להיות שהפורמט של הכתובת הזו לא יתאים לפורמט של הכתובת בשדה postal_address. לדוגמה, התג postal_address תמיד מייצג את המדינה כ-region_code בן 2 אותיות, כגון 'US' או 'NZ'. לעומת זאת, בשדה הזה מצוין שם ארוך יותר של המדינה, כמו 'ארה"ב' או 'ניו זילנד'.
postal_address

PostalAddress

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

AddressComponent

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

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

string

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

string

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

string

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

AddressComponent

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

שדות
component_name

ComponentName

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

string

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

ConfirmationLevel

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

bool

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

bool

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

bool

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

bool

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

ConfirmationLevel

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

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

AddressMetadata

המטא-נתונים של הכתובת. אין ערובה לכך שהשדה metadata יהיה מאוכלס במלואו בכל כתובת שנשלחת אל Address Validation API.

שדות
business

bool

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

bool

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

bool

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

ComponentName

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

שדות
text

string

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

string

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

קואורדינטות

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

שדות
location

LatLng

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

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

PlusCode

ה-Plus Code של location.
bounds

Viewport

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

float

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

string

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

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

string

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

LanguageOptions

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

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

שדות
return_english_latin_address

bool

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

PlusCode

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

שדות
global_code

string

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

string

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

ProvideValidationFeedbackRequest

הבקשה לשליחת משוב על תהליך האימות.

שדות
conclusion

ValidationConclusion

חובה. התוצאה של רצף ניסיונות האימות.

אם השדה הזה מוגדר כ-VALIDATION_CONCLUSION_UNSPECIFIED, תוחזר שגיאת INVALID_ARGUMENT.
response_id

string

חובה. המזהה של התשובה שעבורה נשלח המשוב. הוא אמור להיות [response_id][google.maps.address Validation.v1.VerifyAddressRequest.response_id] מהתגובה הראשונה בסדרה של ניסיונות לאימות כתובת.

ValidationConclusion

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

טיפוסים בני מנייה (enum)
VALIDATION_CONCLUSION_UNSPECIFIED הערך הזה לא בשימוש. אם השדה ProvideValidationFeedbackRequest.conclusion מוגדר ל-VALIDATION_CONCLUSION_UNSPECIFIED, תוחזר שגיאת INVALID_ARGUMENT.
VALIDATED_VERSION_USED הגרסה של הכתובת שהוחזרה על ידי Address Validation API שימשה לעסקה.
USER_VERSION_USED גרסת הכתובת שסופקה על ידי המשתמש שימשה לעסקה
UNVALIDATED_VERSION_USED המערכת השתמשה בגרסה של הכתובת שהוזנה אחרי ניסיון האימות האחרון, אבל לא אומתה מחדש.
UNUSED העסקה ננטשה ולא נעשה שימוש בכתובת.

ProvideValidationFeedbackResponse

אין שדות בסוג הזה.

התשובה למשוב על תהליך האימות.

התגובה תהיה ריקה אם המשוב נשלח בהצלחה.

UspsAddress

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

שדות
first_address_line

string

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

string

שם החברה.
second_address_line

string

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

string

שם של יישוב פוארטוריקני.
city_state_zip_address_line

string

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

string

שם העיר.
state

string

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

string

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

string

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

UspsData

נתוני USPS של הכתובת. לא מובטח ש-uspsData יאוכלס במלואו בכל כתובת בארה"ב או בפורטו ריקו שנשלחת אל Address Validation API. מומלץ לשלב את השדות של כתובת הגיבוי בתגובה אם משתמשים ב-uspsData כחלק העיקרי בתגובה.

שדות
standardized_address

UspsAddress

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

string

קוד בן 2 ספרות של נקודת המסירה
delivery_point_check_digit

string

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

string

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

  • N: לא ניתן היה לאשר את המספר הראשי ואת כל המספרים המשניים באמצעות DPV.
  • D: הכתובת אושרה DPV עבור המספר הראשי בלבד, ופרטי המספר המשני היו חסרים.
  • S: הכתובת אומתה על ידי DPV עבור המספר הראשי בלבד, ומידע על המספר המשני היה קיים אבל לא אומת.
  • Y: הכתובת אומתה על ידי DPV עבור המספר הראשי וכל המספרים המשניים.
  • ריק: אם התגובה לא מכילה ערך dpv_confirmation, הכתובת לא נשלחה לאישור DPV.
dpv_footnote

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: המספר הראשי תואם על ידי השמטת אלפא בסוף
dpv_cmra

string

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

  • Y: הכתובת היא CMRA
  • N: הכתובת היא לא CMRA
dpv_vacant

string

האם המקום הזה פנוי? הפונקציה מחזירה תו יחיד.

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

string

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

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

int32

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

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

string

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

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

string

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

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

string

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

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

int32

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

string

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

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

string

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

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

string

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

  • Y: אין גישה לדלת.
  • N: אין אינדיקציה לכך שאי אפשר לגשת לדלת.
dpv_enhanced_delivery_code

string

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

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

string

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

קידומות:

  • C: מסלול של ספק (או מסלול בעיר)
  • R: מסלול כפרי
  • H: Highway Contract Route
  • B: אזור של תא דואר
  • G: יחידה כללית למשלוח
carrier_route_indicator

string

מחוון למיון של תעריפי נתיבי חברת התובלה.
ews_no_match

bool

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

string

העיר שבה נמצא סניף הדואר הראשי.
post_office_state

string

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

string

עיר מקוצרת.
fips_county_code

string

קוד המחוז ב-FIPS.
county

string

שם המחוז.
elot_number

string

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

string

דגל עלייה/ירידה של eLOT (A/D).
po_box_only_postal_code

bool

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

string

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

string

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

string

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

  • F: FIRM. התאמה לרשומה של חברה, שהיא רמת ההתאמה המדויקת ביותר שאפשר לקבל לכתובת.
  • G: משלוח כללי. התאמה לרשומה של 'כתובת למשלוח דואר'.
  • H: מיקום / דירה. התאמה לרשומה של בניין או דירה.
  • P: תיבת דואר. התוצאה הזו תואמת לתיבת דואר.
  • R: RURAL ROUTE או HIGHWAY CONTRACT: התאמה לרשומה של Rural Route או של Highway Contract. לשתי הרשומות האלה עשויים להיות טווחי מספרי תיבת דואר משויכים.
  • S: רשומת רחוב: התאמה לרשומת רחוב שמכילה טווח מספרים ראשי תקין.
default_address

bool

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

string

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

יכול להיות ששדות הנתונים של USPS לא יאוכלסו כשהשגיאה הזו מופיעה.
cass_processed

bool

אינדיקטור לכך שהבקשה עברה עיבוד CASS.

ValidateAddressRequest

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

שדות
address

PostalAddress

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

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

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

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

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

string

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

bool

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

LanguageOptions

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

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

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.

ValidateAddressResponse

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

שדות
result

ValidationResult

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

string

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

ValidationResult

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

שדות
verdict

Verdict

דגלים של תוצאות כלליות
address

Address

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

Geocode

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

AddressMetadata

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

UspsData

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

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 ב-english_latin_address והשדות google.maps.addressvalidation.v1.AddressComponent.confirmation_level ב-english_latin_address.address_components לא מאוכלסים.

תוצאה

סקירה כללית ברמה גבוהה של תוצאת אימות הכתובת והקואורדינטות שלו.

שדות
input_granularity

Granularity

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

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

Granularity

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

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

Granularity

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

לפעמים הערך הזה עשוי להיות שונה מהערך של validation_granularity שלמעלה. לדוגמה, יכול להיות שבמסד הנתונים שלנו יתועד מספר דירה, אבל לא יהיה מיקום מדויק של הדירה בתוך קומפלקס דירות גדול. במקרה כזה, הערך של validation_granularity יהיה SUB_PREMISE אבל הערך של geocode_granularity יהיה PREMISE.
address_complete

bool

הכתובת נחשבת מלאה אם אין אסימונים שלא נפתרו, ואין רכיבי כתובת לא צפויים או חסרים. אם המדיניות לא מוגדרת, הערך הוא false. פרטים נוספים זמינים בשדות missing_component_types, unresolved_tokens או unexpected.
has_unconfirmed_components

bool

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

bool

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

bool

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