שליחת בקשה לאימות כתובת

כדי לשלוח בקשה לאימות כתובת, שולחים בקשת POST לאחת מנקודות הקצה הבאות:

• validateAddress‏ (REST)
• ValidateAddress‏ (gRPC)

הערה: במסמכי העזרה האלה נעשה שימוש ב-REST בדוגמאות, אבל הגישה דומה גם ל-gRPC.

בבקשה צריך גם להעביר גוף בקשה ב-JSON שמגדיר את הכתובת שרוצים לאמת. גוף הבקשה הבא מכיל שדה אחד ושלושה שדות משנה:

curl -X POST -d '{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  }
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:validateAddress?key=API_KEY"

אפשר גם להשמיט את locality ולציין אותו כרכיב במערך addressLines:

{
  "address": {
    "regionCode": "US",
    "addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
  },
}

רוצים לנסות?

שדות הבקשה לכתובתו

גוף הבקשה מורכב משדה יחיד:

• address – שדה מסוג PostalAddress, שחייב להכיל לפחות רשומה אחת ב-addressLines.

כששולחים את השדה address ל-Address Validation API, צריך לספק רק שדה אחד: addressLines. עם זאת, הבקשה הפשוטה ביותר לקבלת כתובת צריכה לכלול את שדות המשנה הבאים:

• regionCode – מומלץ. זהו שדה אופציונלי, אבל אם משמיטים אותו, המערכת של Address Validation API מסיקה את האזור מהכתובת. עם זאת, כדי לקבל את התוצאות הטובות ביותר, מומלץ לכלול את הערך של regionCode אם הוא ידוע לכם. רשימת האזורים הנתמכים מופיעה במאמר אזורים נתמכים.
• addressLines – חובה. מערך עם כתובות שמתארות את המבנה התחתון של הכתובת.

מידע נוסף זמין במאמר PostalAddress במדריך העזרה.

האפשרות USPS CASS™

שירות הדואר של ארצות הברית (USPS)‏¹ מנהל את מערכת התמיכה בדיווח מדויק על כתובות (CASS™) כדי לתמוך בספקי אימות כתובות ולאשר אותם.

הערה: ה-Address Validation API אושר כשירות בעל אישור CASS-Certified™. כלומר, השירות אושר כי הוא מסוגל למלא פרטי כתובת חסרים, לסטנדרטיזציה שלהם ולעדכן אותם לכתובת העדכנית והמדויקת ביותר.

באזורים בארה"ב ובפורטו ריקו בלבד, אפשר להפעיל עיבוד CASS על ידי הגדרת enableUspsCass לערך true בגוף הבקשה. כדי לקבל את התוצאות הטובות ביותר כשמשתמשים ב-CASS, צריך לספק כתובת שכוללת את הרחוב ומספר הבית, יחד עם העיר, המדינה והמיקוד:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "administrativeArea": "CA",
    "postalCode": "94043",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  },
  "enableUspsCass": true
}

הערה: אם אתם לא זקוקים לעיבוד CASS או שאתם מאמתים כתובות מחוץ לאזורים של ארה"ב ופורטו ריקו, Google לא ממליצה להפעיל את התכונה הזו.

נסה בעצמך!

ב-API Explorer אפשר לשלוח בקשות לדוגמה כדי להתנסות ב-API ובאפשרויות שלו.

1. בוחרים בסמל ה-API, , בצד שמאל של הדף.

2. אפשר גם להרחיב את האפשרות Show standard parameters ולהגדיר את הפרמטר fields למסכת השדה.

3. אם רוצים, עורכים את גוף הבקשה.

4. לוחצים על הלחצן Execute. בתיבת הדו-שיח, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.

5. בחלונית של API Explorer, בוחרים בסמל ההרחבה כדי להרחיב את החלון של API Explorer.

---

1. הפלטפורמה של מפות Google היא בעלת רישיון לא בלעדי של United States Postal Service®. הסימנים המסחריים הבאים הם בבעלות United States Postal Service® והשימוש בהם נעשה ברשות: United States Postal Service®,‏ CASS™, ‏ CASS Certified™. ↩