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 אופציונלי. הרמה המנהלית שמעל לרשות המוניציפאלית שמשמשת לכתובות למשלוח דואר במדינה או באזור. לדוגמה, מדינה, מחוז, אזור או תחום שיפוט. בספרד, צריך לציין את המחוז ולא את הקהילה האוטונומית (לדוגמה, 'ברצלונה' ולא 'קטלוניה'). במדינות רבות לא משתמשים באזור אדמיניסטרטיבי בכתובות למשלוח דואר. לדוגמה, בשווייץ, לא צריך להזין ערך.
locality	string אופציונלי. בדרך כלל מתייחס לחלק של העיר או העיירה בכתובת. דוגמאות: עיר בארה"ב, קומונה באיטליה, עיר עם סניף דואר בבריטניה. באזורים בעולם שבהם היישובים לא מוגדרים היטב או לא מתאימים למבנה הזה, משאירים את locality ריק ומשתמשים ב-addressLines.
sublocality	string אופציונלי. האזור המשני שמוגדר בכתובת. לדוגמה, שכונה, רובע או מחוז.
addressLines[]	string שורות כתובת לא מובנות שמתארות את הרמות הנמוכות יותר של כתובת. מכיוון שלערכים ב-addressLines אין מידע על סוג, ולפעמים הם יכולים להכיל כמה ערכים בשדה אחד (לדוגמה, 'אוסטין, טקסס'), חשוב שסדר השורות יהיה ברור. הסדר של שורות הכתובת צריך להיות הסדר שבו הכתובת מופיעה על המעטפה במדינה או באזור שבהם הכתובת נמצאת. במקומות שבהם יכול להיות הבדל (לדוגמה, יפן), משתמשים ב-address_language כדי לציין את זה במפורש (לדוגמה, 'ja' לסידור ממידה גדולה למידה קטנה ו-'ja-Latn' או 'en' לסידור ממידה קטנה למידה גדולה). כך אפשר לבחור את השורה הספציפית ביותר של כתובת על סמך השפה. הייצוג המבני המינימלי המותר של כתובת מורכב מ-regionCode עם כל שאר המידע שמוצב ב-addressLines. אפשר לעצב כתובת כזו באופן משוער מאוד בלי לבצע גיאו-קידוד, אבל אי אפשר להסיק מסקנות סמנטיות לגבי אף אחד מרכיבי הכתובת עד שהיא נפתרת לפחות באופן חלקי. הדרך המומלצת לטפל בכתובות לא מובנות לחלוטין (בניגוד לניסיון לנחש אילו חלקים בכתובת צריכים להיות יישובים או אזורים אדמיניסטרטיביים) היא ליצור כתובת שמכילה רק regionCode ו-addressLines ואז לבצע קידוד גיאוגרפי.
recipients[]	string אופציונלי. הנמען בכתובת. בנסיבות מסוימות, השדה הזה עשוי להכיל מידע בכמה שורות. לדוגמה, יכול להיות שיופיע בו מידע כמו 'לטיפולו של'.
organization	string אופציונלי. שם הארגון בכתובת.