Package google.maps.addressvalidation.v1

אינדקס

AddressValidation

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

ProvideValidationFeedback

rpc ProvideValidationFeedback(ProvideValidationFeedbackRequest) returns (ProvideValidationFeedbackResponse)

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

rpc ValidateAddress(ValidateAddressRequest) returns (ValidateAddressResponse)

מאמת כתובת.

כתובת

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

שדות
formatted_address

string

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

PostalAddress

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

AddressComponent

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

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

string

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

string

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

string

אסימונים בקלט שלא ניתן לפענח. יכול להיות שמדובר בקלט שלא זוהה כחלק תקין של כתובת (לדוגמה בקלט כמו " 123235253253 ראשי תל אביב, תל אביב, ישראל, 64340", האסימונים שלא זוהו עשויים להיראות כך: ["123235253253"] כי נראה שהמספר הזה לא נראה כמו מספר בית חוקי.

AddressComponent

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

שדות
component_name

ComponentName

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

string

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

ConfirmationLevel

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

bool

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

bool

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

bool

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

bool

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

ConfirmationLevel

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

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

AddressMetadata

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

שדות
business

bool

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

bool

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

bool

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

ComponentName

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

שדות
text

string

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

string

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

קואורדינטות

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

שדות
location

LatLng

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

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

PlusCode

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

Viewport

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

float

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

string

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

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

string

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

LanguageOptions

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

שדות
global_code

string

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

string

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

ProvideValidationFeedbackRequest

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

שדות
conclusion

ValidationConclusion

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

אם קובעים בשדה הזה את הערך VALIDATION_CONCLUSION_UNSPECIFIED, תוחזר הודעת השגיאה INVALID_ARGUMENT.
response_id

string

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

ValidationConclusion

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

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

קוד מצב בן 2 אותיות.
zip_code

string

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

string

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

UspsData

נתוני USPS עבור הכתובת. לא בטוח שהשדה uspsData יאוכלס במלואו לכל כתובת בארה"ב או כתובת PR שנשלחת אל 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_digital, מיקוד ו-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: חסר מספר תיבת הזמנת רכש, RR או מרכז עזרה של כתובת קלט
  • P3: מספר הזמנת רכש, RR או תיבת מרכז העזרה של הכתובת שהזנת לא תקין
  • 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 (מכללות, צבא וסוגים אחרים) - רשומות ZIP + 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 – יום שישי הוא יום שבו לא נמסרה מסירה אוטומטית
dpv_no_secure_location

string

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

  • Y: מטעמי אבטחה, החבילה לא תישאר.
  • N: מטעמי אבטחה, אין אינדיקציה שהחבילה לא תישאר.
dpv_pbsa

string

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

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

string

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

  • 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: מסלול לחוזה בכביש מהיר
  • 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: POST OFFICE BOX. הקישור הזה מתאים לתיבת דואר.
  • R: 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 בתור "פוארטו ריקו" (לא תלוי-רישיות) או "PR".

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

LanguageOptions

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

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

string

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

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

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

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

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

Granularity

רמת הפירוט שבה ה-API יכול validate את הכתובת במלואה. לדוגמה, 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.

רמת פירוט

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

טיפוסים בני מנייה (enums)
GRANULARITY_UNSPECIFIED ערך ברירת המחדל. הערך הזה לא בשימוש.
SUB_PREMISE תוצאה מתחת לקומה של הבניין, למשל דירה.
PREMISE תוצאה ברמת הבניין.
PREMISE_PROXIMITY קואורדינטות שמקבילות למיקום של הכתובת ברמת הבניין.
BLOCK הכתובת או המיקוד הגיאוגרפי מציינים בלוק. בשימוש רק באזורים עם כתובות ברמת בלוק, כמו יפן.
ROUTE המיקוד הגיאוגרפי או הכתובת מפורטים למסלול, כמו רחוב, כביש או כביש מהיר.
OTHER כל שאר רמות הפירוט, שמקובצות יחד כי לא ניתן להעביר אותן.