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/ territories_information.html. דוגמה: 'CH' עבור שווייץ.
languageCode	string אופציונלי. קוד שפה BCP-47 של תוכן הכתובת הזו (אם ידוע). בדרך כלל, זוהי שפת ממשק המשתמש של טופס הקלט או שהוא אמור להתאים לאחת מהשפות המשמשות במדינה/באזור של הכתובת, או בתעתיקים המקבילים להן. היא יכולה להשפיע על הפורמט במדינות מסוימות, אך אינה קריטית לתקינות הנתונים ואף פעם לא תשפיע על אימות כלשהו או על פעולות אחרות שלא קשורות לפורמט. אם הערך לא ידוע, צריך להשמיט אותו (במקום לציין ברירת מחדל שעלולה להיות שגויה). דוגמאות: "zh-Hant", "ja", "ja-Latn", "en".
postalCode	string אופציונלי. המיקוד של הכתובת. לא כל המדינות משתמשות או דורשות מיקודי דואר, אך במקומות שבהם הן בשימוש, הן עשויות להפעיל אימות נוסף עם חלקים אחרים של הכתובת (למשל, אימות מדינה/מיקוד בארה"ב).
sortingCode	string אופציונלי. קוד מיון נוסף, ספציפי למדינה. ההגדרה הזו לא בשימוש ברוב האזורים. כאשר משתמשים בו, הערך הוא מחרוזת כגון "CEDEX", ולאחר מכן מספר (למשל "CEDEX 7"), או רק מספר בלבד, שמייצג את "קוד הסקטור" (ג'מייקה), "מחוון אזור משלוח" (מלאווי) או "חיווי סניף דואר" (למשל חוף השנהב).
administrativeArea	string אופציונלי. חלוקת המשנה המנהלית הגבוהה ביותר המשמשת לכתובות דואר במדינה או באזור. לדוגמה: מדינה, מחוז, אובלסט או מחוז. ספציפית בספרד, זו הפרובינציה ולא הקהילה האוטונומית (למשל "ברצלונה" ולא "קטלוניה"). מדינות רבות לא משתמשות באזור מנהלי בכתובות דואר. למשל, בשווייץ צריך להשאיר את השדה הזה לא מאוכלס.
locality	string אופציונלי. מתייחס בדרך כלל לחלק של העיר/העיר. דוגמאות: עיר בארה"ב, קהילת IT, עיר דואר בריטית. באזורים בעולם שבהם הרשויות אינן מוגדרות היטב או שאינן מתאימות למבנה הזה, יש להשאיר את היישוב ריק ולהשתמש ב-addressLine.
sublocality	string אופציונלי. אזור המשנה של הכתובת. לדוגמה: שכונות, רובעים ומחוזות.
addressLines[]	string שורות כתובת לא מובנות המתארות את הרמות הנמוכות יותר של כתובת. מכיוון שלערכים ב-addressLine אין מידע על סוג והם עשויים להכיל לפעמים ערכים מרובים בשדה אחד (למשל "אוסטין, טקסס"), ולכן חשוב שסדר השורות יהיה ברור. הסדר של שורות הכתובת צריך להיות "מעטפה הזמנה" עבור המדינה/האזור של הכתובת. במקומות שבהם הטקסט עשוי להשתנות (למשל, יפן), address_language משמשת כדי לציין את התוכן הזה באופן מפורש (למשל, "ja" להזמנה קטנה-גדולה ו-"ja-Latn" או "en" לאותיות קטנות עד גדולות). בצורה כזו אפשר לבחור את השורה הספציפית ביותר של כתובת על סמך השפה. הייצוג המבני המינימלי המותר של כתובת מורכב מ-regionCode עם כל המידע שנותר ב-addressLines. אפשר לעצב כתובת כזו באופן משוער מאוד ללא קידוד גיאוגרפי, אך לא ניתן יהיה לתלות סמנטית באף אחד מרכיבי הכתובת עד לפתרון חלקי בלבד. יצירת כתובת המכילה קוד אזור ושורות כתובת בלבד, ולאחר מכן קידוד גיאוגרפי היא הדרך המומלצת לטפל בכתובות לא מובנות לחלוטין (בניגוד לניחוש אילו חלקים בכתובת צריכים להיות אזורים או אזורים מנהליים).
recipients[]	string אופציונלי. הנמען בכתובת. בנסיבות מסוימות, השדה הזה עשוי להכיל מידע מרובה שורות. לדוגמה, יכול להיות שהוא מכיל מידע על "טיפול".
organization	string אופציונלי. שם הארגון בכתובת.