पते की पुष्टि से जुड़े बुनियादी जवाब को समझना

Address Validation API, response body को JSON ऑब्जेक्ट के तौर पर उपलब्ध कराता है. इसमें दो टॉप-लेवल प्रॉपर्टी होती हैं:

  • result, ValidationResult टाइप का ऑब्जेक्ट
  • responseID
{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

इस दस्तावेज़ में result ऑब्जेक्ट के बारे में बताया गया है. responseID के बारे में जानकारी के लिए, अपडेट किए गए पतों को मैनेज करना लेख पढ़ें.

verdict प्रॉपर्टी

verdict प्रॉपर्टी, पते की पुष्टि करने के नतीजों की खास जानकारी देती है. साथ ही, पते की जांच करने का लॉजिक बनाते समय, इस प्रॉपर्टी का आकलन सबसे पहले किया जाना चाहिए. यह प्रॉपर्टी, आउटपुट पते की क्वालिटी के आधार पर कई फ़ील्ड दिखा सकती है. उदाहरण के लिए, यहां अच्छी क्वालिटी वाले पते की verdict प्रॉपर्टी दिखाई गई है. यह इस अनुरोध के लिए चार फ़ील्ड दिखाती है:

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true,
  "possibleNextAction": "ACCEPT"
}

यहां दिए गए सेक्शन में, verdict प्रॉपर्टी के सभी फ़ील्ड के बारे में खास जानकारी दी गई है.

रेफ़रंस गाइड में Verdict देखें.

अगली संभावित कार्रवाई

possibleNextAction प्रॉपर्टी, एपीआई के बाकी जवाब की व्याख्या वाली खास जानकारी देती है. इसका मकसद यह तय करने में आपकी मदद करना है कि आपको अपने ग्राहक को उसके पते की समीक्षा करने या उसमें बदलाव करने के लिए कहना चाहिए या नहीं. ज़्यादा जानकारी के लिए, मान्य करने का लॉजिक बनाना लेख पढ़ें.

पते की जानकारी का स्तर

पते की बारीकी से मतलब है कि किसी पते या जियोकोड की खास जानकारी का पता लगाने के लिए, किस लेवल की जानकारी का इस्तेमाल किया गया है. validationGranularity जवाब में पते की जानकारी का सटीक होना, यह तय करने के लिए एक अहम सिग्नल है कि पते पर डिलीवरी की जा सकती है या नहीं.

verdict प्रॉपर्टी, ये ग्रेन्यूलैरिटी सिग्नल दिखाती है:

  • inputGranularity — इससे, Address Validation API को भेजे गए पते से कैप्चर की गई जानकारी के लेवल के बारे में पता चलता है. अनुरोध में पते की जानकारी के लेवल से, पुष्टि के जवाब में पते की जानकारी के लेवल पर असर पड़ता है. उदाहरण के लिए, अगर किसी पते में PREMISE लेवल से नीचे inputGranularity लेवल है, तो आम तौर पर उसे PREMISE लेवल से validationGranularity लेवल में नहीं बदला जाता.
  • validationGranularity — यह वह ग्रैन्युलैरिटी लेवल है जिस पर Address Validation API, पते की पूरी तरह से पुष्टि कर सकता है. ज़्यादातर मामलों में, PREMISE या SUB_PREMISE के ग्रैन्युलैरिटी लेवल से पता चलता है कि पता सही है और इस पर डिलीवरी की जा सकती है.
  • geocodeGranularity — इससे पते से जुड़े जियोकोड की जानकारी के लेवल के बारे में पता चलता है. उदाहरण के लिए, Google के रिकॉर्ड में अपार्टमेंट नंबर की जानकारी हो सकती है. हालांकि, बड़े अपार्टमेंट कॉम्प्लेक्स में उस अपार्टमेंट की सटीक जगह की जानकारी नहीं होती. ऐसे मामले में, validationGranularity SUB_PREMISE है, लेकिन geocodeGranularityisPREMISE`.
रेफ़रंस गाइड में, ग्रैनुलैरिटी देखें.

पते की पूरी जानकारी

फ़ैसले में addressComplete प्रॉपर्टी को अच्छी क्वालिटी वाले पते के सिग्नल के तौर पर दिखाया जाता है. इसका मतलब है कि इसमें कोई भी कॉम्पोनेंट मौजूद नहीं है, हल नहीं हुआ है या अनचाहा नहीं है:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true,
    "possibleNextAction": "ACCEPT"
}

अगर पते में कोई कॉम्पोनेंट मौजूद नहीं है, हल नहीं किया गया है या अनचाहा है, तो फ़ील्ड को false पर सेट किया जाता है.

रेफ़रंस गाइड में, Verdict और पता के नीचे addressComplete देखें.

पते की क्वालिटी

कई संभावित फ़ील्ड, पते के कॉम्पोनेंट में मौजूद समस्याओं या उनमें किए गए बदलावों के बारे में बताते हैं. जैसे, अनुमानित या छूटे हुए पते के कॉम्पोनेंट. उदाहरण के लिए, यहां दी गई verdict प्रॉपर्टी से ऐसे पते का पता चलता है जिसके कॉम्पोनेंट की पुष्टि नहीं हुई है. साथ ही, इसमें addressComplete फ़ील्ड मौजूद नहीं है:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
रेफ़रंस गाइड में Verdict के बारे में पढ़ें.

address और addressComponent प्रॉपर्टी

address प्रॉपर्टी, अनुरोध में दिए गए प्रोसेस किए गए पते के लिए फ़ॉर्मैटिंग उपलब्ध कराती है. साथ ही, पते के कॉम्पोनेंट-लेवल की खास जानकारी भी देती है. इसमें पते के गलत स्पेलिंग वाले हिस्से, बदले गए गलत हिस्से, और अनुमानित तौर पर जोड़े गए हिस्से शामिल हैं.

रेफ़रंस गाइड में Address देखें.

addressComponent प्रॉपर्टी, address का एक सबकॉम्पोनेंट है. यह पते के उन एलिमेंट या कॉम्पोनेंट की पूरी सूची दिखाता है जिन्हें Address Validation API ने प्रोसेस किया है. एपीआई, हर कॉम्पोनेंट फ़ील्ड की पहचान उसके नाम, टाइप, और पुष्टि के लेवल से करता है.

रेफ़रंस गाइड में addressComponent देखें.

geocode प्रॉपर्टी

geocode प्रॉपर्टी, इनपुट किए गए पते से जुड़ी जियोकोड की गई जगह की जानकारी दिखाती है. इस प्रॉपर्टी से जगह की जानकारी मिलती है. जैसे, जगह का आईडी.

रेफ़रंस गाइड में Geocode देखें.

metadata प्रॉपर्टी

ऐसा हो सकता है कि यह प्रॉपर्टी, Address Validation API से प्रोसेस किए गए हर पते के लिए न भरी गई हो. हालांकि, इससे यह पता चलता है कि पता घर, कारोबार या पीओ बॉक्स का है.

Address Validation API की कवरेज और Address metadata के रेफ़रंस देखें.

uspsData प्रॉपर्टी

यह प्रॉपर्टी, अमेरिका के डाक पतों के लिए काम की जानकारी देती है. हालांकि, इस बात की गारंटी नहीं है कि सेवा से पुष्टि किए गए हर पते के लिए, यह फ़ील्ड पूरी तरह से भरा गया हो. इसलिए, आपको सिर्फ़ इस प्रॉपर्टी पर भरोसा नहीं करना चाहिए. इसके बजाय, verdict और address की भी जांच करनी चाहिए.

अमेरिका के पतों को मैनेज करना और UspsData का रेफ़रंस देखें.