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