PostalAddress

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

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

עצה לגבי קלט / עריכה של כתובת: - השתמשו בווידג'ט של כתובת שמותאמת ל-i18n, כמו 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 של המדינה/האזור של הכתובת. אנחנו אף פעם לא מסיקים זאת, והמשתמש הוא אחראי לוודא שהערך שלו נכון. פרטים נוספים זמינים בכתובת http://cldr.unicode.org/ ו-http://www.unicode.org/cldr/charts/30/supplemental/region_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, עיר דואר בריטית. באזורים בעולם שבו השכונות אינן מוגדרות היטב או שאינן מתאימות למבנה זה, יש להשאיר את הרשות המוניציפאלית ריקה ולהשתמש ב-addressLines.
sublocality

string

אופציונלי. אזור משנה של הכתובת. לדוגמה: שכונות, רובעים או מחוזות.
addressLines[]

string

שורות כתובת לא מובנות שמתארות את הרמות הנמוכות יותר של כתובת.

מכיוון שלערכים ב-addressLine אין מידע על סוג, ולפעמים הם יכולים להכיל כמה ערכים בשדה אחד (למשל, אוסטין, טקסס), חשוב שסדר השורות יהיה ברור. סדר השורות צריך להיות מסוג 'סדר מעטפות' עבור המדינה/האזור של הכתובת. במקומות שבהם זה יכול להשתנות (לדוגמה, יפן), address_language משמשת כדי לציין את המחרוזת באופן מפורש (למשל, "ja" עבור הזמנה גדולה עד קטנה ו-"ja-Latn" או "en" עבור קטן עד גדול). בצורה כזו אפשר לבחור את השורה הספציפית ביותר של כתובת בהתאם לשפה.

הייצוג המבני המינימלי המותר של כתובת מורכב מ-regionCode עם כל שאר המידע שממוקם ב-addressLines. ניתן יהיה לכתוב כתובת כזו באופן כמעט משוער ללא קידוד גיאוגרפי, אך לא תהיה אפשרות לנמק סמנטי על רכיבי הכתובת עד שתפתרו אותה לפחות באופן חלקי.

יצירת כתובת שמכילה רק קוד אזור ושורות כתובת, ולאחר מכן קידוד גיאוגרפי היא הדרך המומלצת לטפל בכתובות לא מובנות לחלוטין (במקום לנחש אילו חלקי הכתובת אמורים להיות אזורים או אזורים מנהליים).
recipients[]

string

אופציונלי. הנמען בכתובת. בנסיבות מסוימות, שדה זה עשוי להכיל מידע מרובה שורות. לדוגמה, הוא עשוי לכלול מידע על "טיפול ב".
organization

string

אופציונלי. שם הארגון בכתובת