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 זה שינוי אופציונלי. שם הארגון בכתובת.