PostalAddress

• ייצוג ב-JSON

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

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

עצות להזנה או לעריכה של כתובות: - כדאי להשתמש בווידג'ט כתובות שמותאם לתרגום לשפות שונות, כמו 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, שהוא הגרסה האחרונה. כל הגרסאות החדשות צריכות להיות תואמות לאחור לגרסאות הישנות.
regionCode	string חובה. קוד האזור במאגר CLDR של המדינה או האזור של הכתובת. המערכת אף פעם לא מסיקה את הערך הזה, והמשתמש צריך לוודא שהערך נכון. פרטים נוספים זמינים בכתובות https://cldr.unicode.org/ ו-https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html. דוגמה: 'CH' לשווייץ.
languageCode	string אופציונלי. קוד השפה מסוג BCP-47 של התוכן בכתובת הזו (אם ידוע). בדרך כלל זו שפת ממשק המשתמש של טופס הקלט, או שהיא אמורה להתאים לאחת מהשפות שבהן נעשה שימוש במדינה או באזור של הכתובת, או לשמות המקבילים שלהן בכתב לטינית. הדבר עשוי להשפיע על הפורמט במדינות מסוימות, אבל הוא לא קריטי לנכונות הנתונים, ולעולם לא ישפיע על תיקוף או על פעולות אחרות שלא קשורות לפורמט. אם הערך הזה לא ידוע, צריך להשמיט אותו (במקום לציין ערך ברירת מחדל שעלול להיות שגוי). דוגמאות: 'zh-Hant',‏ 'ja',‏ 'ja-Latn',‏ 'en'.
postalCode	string אופציונלי. המיקוד של הכתובת. לא בכל המדינות משתמשים במיקוד או מחייבים להוסיף אותו, אבל במדינות שבהן משתמשים בו, הוא עשוי להפעיל אימות נוסף של חלקים אחרים בכתובת (לדוגמה, אימות של מדינה או מיקוד בארצות הברית).
sortingCode	string אופציונלי. קוד מיון נוסף, ספציפי למדינה. ברוב האזורים לא נעשה שימוש באפשרות הזו. במקרים שבהם הוא משמש, הערך הוא מחרוזת כמו 'CEDEX', אחריה יכול להופיע מספר (לדוגמה, 'CEDEX 7') או רק מספר, שמייצג את 'קוד התחום' (ג'מייקה), 'מחוון אזור המסירה' (מלווי) או 'מחוון סניף הדואר' (חוף השנהב).
administrativeArea	string אופציונלי. הרמה המנהלית הגבוהה ביותר שמשמשת לכתובות דואר של מדינה או אזור. לדוגמה, מדינה, מחוז, oblast או מחוז. בספרד, זהו המחוז ולא הקהילה האוטונומית (לדוגמה, 'Barcelona' ולא 'Catalonia'). במדינות רבות לא נהוג לציין אזור אדמיניסטרטיבי בכתובות דואר. לדוגמה, בשווייץ, השדה הזה צריך להישאר ריק.
locality	string אופציונלי. בדרך כלל מתייחס לחלק של העיר או העיירה בכתובת. דוגמאות: עיר בארה"ב, עיר בבריטניה, יישוב בבריטניה. באזורים בעולם שבהם התחומים המקומיים לא מוגדרים היטב או לא מתאימים למבנה הזה, משאירים את השדה locality ריק ומשתמשים בשדה addressLines.
sublocality	string אופציונלי. יישוב משנה של הכתובת. לדוגמה, יכול להיות שמדובר בשכונה, ברחוב או בעיר.
addressLines[]	string שורות כתובת לא מובנות שמתארות את הרמות הנמוכות יותר של הכתובת. מכיוון שלערכים ב-addressLines אין פרטי טיפוס, ולפעמים הם מכילים כמה ערכים בשדה אחד (לדוגמה, 'תל אביב, תל אביב'), חשוב שהסדר של השורות יהיה ברור. סדר שורות הכתובת צריך להיות 'סדר המעטפה' של המדינה או האזור של הכתובת. במקומות שבהם המשמעות יכולה להשתנות (לדוגמה, יפן), משתמשים ב-address_language כדי לציין זאת בבירור (לדוגמה, 'ja' לסדר מגדול לקטן ו-'ja-Latn' או 'en' לסדר מקטן לגדול). כך אפשר לבחור את השורה הספציפית ביותר של הכתובת על סמך השפה. הייצוג המבני המינימלי המותר של כתובת מורכב מ-regionCode, כאשר כל המידע הנותר ממוקם ב-addressLines. אפשר יהיה לעצב כתובת כזו באופן גס מאוד בלי גיאוקוד, אבל לא ניתן יהיה להסיק מסקנות סמנטיות לגבי אף אחד מרכיבי הכתובת עד שהיא תטופל לפחות באופן חלקי. הדרך המומלצת לטיפול בכתובות ללא מבנה היא ליצור כתובת שמכילה רק את השדות regionCode ו-addressLines, ולאחר מכן לבצע גיאוקוד. הדרך הזו עדיף על פני ניחוש אילו חלקים בכתובת צריכים להיות יישוב או תחום אדמיניסטרטיבי.
recipients[]	string אופציונלי. הנמען בכתובת. יכול להיות שבנסיבות מסוימות השדה הזה יכיל מידע בכמה שורות. לדוגמה, יכול להיות שהוא מכיל פרטים לגבי 'מי שצריך לפנות אליו'.
organization	string אופציונלי. שם הארגון בכתובת.