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

पते की पुष्टि करने वाला एपीआई, 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
}

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

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

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

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

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

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

पता पूरा होना

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

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

जब पता मौजूद नहीं होता है, जिसका समाधान नहीं किया जाता है या जिसकी उम्मीद नहीं की जाती है, उसके लिए फ़ील्ड को false पर सेट किया जाता है.

रेफ़रंस गाइड में, फ़ैसला और पता में जाकर, addressComplete देखें.

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

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

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
रेफ़रंस गाइड में फ़ैसला देखें.

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

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

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

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

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

geocode प्रॉपर्टी

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

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

metadata प्रॉपर्टी

ऐसा हो सकता है कि इस प्रॉपर्टी में, पते की पुष्टि करने वाले एपीआई की मदद से प्रोसेस किए गए हर पते का डेटा अपने-आप न भर पाए. हालांकि, इससे पता चलता है कि पता घर का है, कारोबार का है या पीओ बॉक्स का है.

पते की पुष्टि करने वाले एपीआई की कवरेज और Address metadata का रेफ़रंस देखें.

uspsData प्रॉपर्टी

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

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