पते की पुष्टि करने का बुनियादी तरीका समझना

पते की पुष्टि करने वाला एपीआई, इनपुट के तौर पर पता लेता है. इसके बाद, एपीआई जवाब देता है, जिसमें:

  • पूरे पते की पुष्टि के लिए और पते के हर कॉम्पोनेंट (सड़क का नंबर, सड़क का नाम, शहर वगैरह) की पुष्टि के लिए फ़ैसला.

  • एक स्ट्रिंग, जिसमें एपीआई से तय किए गए पूरे पते की जानकारी होती है.

  • एपीआई के तय किए गए हिसाब से, पते का हर कॉम्पोनेंट वाली अलग-अलग प्रॉपर्टी.

  • पता कॉम्पोनेंट के मौजूद न होने की सूची, पता कॉम्पोनेंट की पुष्टि न होना, और पते के उन कॉम्पोनेंट की सूची जिनका समाधान नहीं किया जा सकता.

  • पते का जियोकोड.

  • "US" और "PR" क्षेत्रों के लिए, पते के लिए USPS डेटा.

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

इस दस्तावेज़ में एपीआई के रिस्पॉन्स को प्रोसेस करने और इनपुट पते की कुछ सामान्य गड़बड़ियों को ठीक करने का तरीका बताया गया है.

ध्यान दें: एपीआई, इनपुट पते से जुड़ी गड़बड़ियों को कैसे हैंडल करता है, इस बारे में बेहतर जानकारी पाने के लिए डेमो आज़माएं. डेमो की मदद से पते डाले जा सकते हैं. इसके बाद, रिस्पॉन्स को विज़ुअलाइज़ किए गए कॉन्टेंट और JSON ऑब्जेक्ट के तौर पर देखा जा सकता है.

जवाब के बारे में जानकारी

पुष्टि का रिस्पॉन्स दिखाने वाले JSON ऑब्जेक्ट में, दो टॉप-लेवल प्रॉपर्टी शामिल होती हैं: result टाइप की वैलिडेशन वेबसाइट, और 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 प्रॉपर्टी में ये प्रॉपर्टी शामिल हैं:

  • inputGranularity

    इनपुट पते की बारीकियों के बारे में बताता है, जैसा कि पते को पार्स करके तय किया गया है, लेकिन उसकी पुष्टि नहीं की गई है. उदाहरण के लिए, इन प्रॉपर्टी में PREMISE, बिल्डिंग लेवल पर नतीजे तक पहुंचने वाले पते के लिए, BLOCK उस पते के लिए शामिल हो सकता है जो ब्लॉक तक ले जाता है. इसके अलावा, किसी रास्ते, जैसे कि सड़क, सड़क या हाइवे के पते की जानकारी के लिए, ROUTE का इस्तेमाल किया जा सकता है.

  • validationGranularity

    इससे पता चलता है कि एपीआई, पते की पुष्टि कर सकता है या नहीं. ध्यान दें कि यह पुष्टि किए गए पते की जानकारी का लेवल है, न कि address.formattedAddress या address.postalAddress में दिए गए पते की जानकारी.

  • geocodeGranularity

    जनरेट किए गए जियोकोड की जगह की जानकारी देता है.

  • addressComplete

    अगर एपीआई ने पते को पूरा माना है, तो वैल्यू 'सही' होगी. इसका मतलब है कि address प्रॉपर्टी में कोई भी ऐसा टोकन (पते की स्ट्रिंग या सिंबल), अनचाहे पते वाले कॉम्पोनेंट, या पता वाले कॉम्पोनेंट मौजूद नहीं हैं जिन्हें सुलझाया नहीं गया है.

  • hasUnconfirmedComponents, hasInferredComponents, hasReplacedComponents

    ऐसी प्रॉपर्टी जिनसे पता चलता है कि कम से कम एक पते वाले कॉम्पोनेंट को कैटगरी में बांटा जा सकता है या उसकी पुष्टि नहीं की जा सकती. साथ ही, यह भी पता चलता है कि पते का कम से कम एक कॉम्पोनेंट जोड़ा गया है (जोड़ा गया) और इनपुट में शामिल नहीं किया गया था. साथ ही, पते से जुड़े कम से कम एक कॉम्पोनेंट को बदला गया था या नहीं.

अनुमानित कॉम्पोनेंट के साथ पूरे पते के लिए फ़ैसला

इस उदाहरण में, अनुमानित कॉम्पोनेंट के साथ पूरे पते के लिए verdict प्रॉपर्टी दिखाई गई है:

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

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

पुष्टि न किए गए कॉम्पोनेंट वाले पते के लिए फ़ैसला

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

अगले उदाहरण में, hasUnconfirmedComponents को true पर सेट किया गया है. इससे पता चलता है कि पते में, पते का कम से कम एक कॉम्पोनेंट है जिसे कैटगरी में बांटा नहीं जा सकता या उसकी पुष्टि नहीं की जा सकती:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

इस मामले में, पुष्टि किए गए और जियोकोड किए गए पते की जानकारी का स्तर OTHER पर सेट होता है. साथ ही, addressComplete प्रॉपर्टी को जवाब में शामिल नहीं किया जाता है, ताकि यह बताया जा सके कि पूरा पता नहीं है. बेहतर उदाहरण के लिए, पते के ऐसे कॉम्पोनेंट मौजूद नहीं हैं और जिनकी पुष्टि नहीं हुई है देखें.

जवाब के उदाहरण

नीचे दिए गए सेक्शन अलग-अलग स्थितियों के हिसाब से जवाब दिखाते हैं. इनमें पूरे पते और पते की पुष्टि करने में आम तौर पर होने वाली गड़बड़ियां शामिल हैं. इन उदाहरणों में:

  • अगर रिस्पॉन्स में addressComplete है, जो true पर सेट है, तो एपीआई यह पता लगाता है कि इनपुट का पता अच्छी क्वालिटी का था.

  • अगर पते की पुष्टि करने वाले एपीआई से पता चलता है कि उसने पते में अहम बदलाव किए हैं या पते में गड़बड़ियां हैं, तो आपको ग्राहक के साथ, लौटाए गए पते की पुष्टि करनी होगी.

अच्छी क्वालिटी वाला पूरा पता

जब एपीआई को पता चलता है कि कोई पता पूरा हो गया है, तो रिस्पॉन्स की verdict प्रॉपर्टी में वह addressComplete को true पर सेट कर देता है.

उदाहरण के लिए:

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

रिस्पॉन्स की address प्रॉपर्टी में, एपीआई से तय किए गए पते की सारी जानकारी शामिल होती है. रिस्पॉन्स में formattedAddress प्रॉपर्टी शामिल होती है, जिसमें एक लाइन वाली स्ट्रिंग के रूप में सही और पुष्टि किया गया पता शामिल होता है. हमारा सुझाव है कि पूरे पते के लिए, formattedAddress फ़ील्ड में मौजूद सिंगल-लाइन पते का इस्तेमाल करें. इसमें, पते में मामूली सुधार के साथ-साथ, कुछ और चीज़ें जोड़ी जा सकती हैं. जैसे, अंग्रेज़ी के बड़े अक्षरों का इस्तेमाल और अमेरिका में ZIP+4.

address प्रॉपर्टी से यह भी पता चलता है कि क्या एपीआई हर पते से जुड़े कॉम्पोनेंट में कोई समस्या है. सड़क के नाम या शहर जैसे हर कॉम्पोनेंट के लिए, address फ़ील्ड में एक confirmationLevel फ़ील्ड होता है. इसमें ये वैल्यू शामिल हो सकती हैं:

  • CONFIRMED से पता चलता है कि एपीआई यह पुष्टि कर पाया कि कॉम्पोनेंट मौजूद है
  • UNCONFIRMED_BUT_PLAUSIBLE बताता है कि कॉम्पोनेंट की पुष्टि नहीं की जा सकी, लेकिन यह हो सकता है
  • UNCONFIRMED_AND_SUSPICIOUS से पता चलता है कि कॉम्पोनेंट की पुष्टि नहीं हुई थी और यह गलत हो सकता है.

उदाहरण के लिए:

"address": {
  // Validated address as a single string.
  "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
  // Individual validated address components.
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043-1351",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  // Validation results for each component.
  "addressComponents": [
    {
      "componentName": {
        "text": "1600",
        "languageCode": "en"
      },
      "componentType": "street_number",
      "confirmationLevel": "CONFIRMED"
    },
    {
      "componentName": {
        "text": "Amphitheatre Pkwy",
        "languageCode": "en"
      },
      "componentType": "route",
      "confirmationLevel": "CONFIRMED"
    },
    …
  ]
  // List of any missing, unconfirmed, or unresolved address components.
  // These properties are omitted from the response if they are empty.
  "missingComponentTypes": [],
  "unconfirmedComponentTypes": [],
  "unresolvedTokens": []
}

अनुमानित पते के कॉम्पोनेंट

अगर इनपुट पते में पूरा पता नहीं दिया गया है, तो एपीआई, रिस्पॉन्स में पते के ऐसे कॉम्पोनेंट जोड़ने की कोशिश करता है जो उपलब्ध नहीं हैं. जोड़े गए इन कॉम्पोनेंट को अनुमानित पता वाले कॉम्पोनेंट कहा जाता है.

उदाहरण के लिए, इस इनपुट पते का इस्तेमाल किया जा रहा है:

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

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

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

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

अनुमान लगाए गए कॉम्पोनेंट के लिए, एपीआई address प्रॉपर्टी के addressComponents ऐरे से जुड़े एलिमेंट में inferred को true पर सेट करता है:

{
  "componentName": {
    "text": "94043"
  },
  "componentType": "postal_code",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
}

इनपुट पते में वर्तनी की गड़बड़ियां

इनपुट पते में वर्तनी की गड़बड़ियां, जैसे कि शहर या राज्य में टाइपिंग की गलतियां होना आम हैं. उदाहरण के लिए, "माउंटेन व्यू" के बजाय, आप किसी पते के इलाके के रूप में "MontainView" डालें:

{
  "address": {
    "regionCode" : "US",
    "locality" : "MontainView",
    "addressLines" : ["1600 Amphitheatre Pkwy"]
  }
}

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

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

एपीआई, पते को सही स्पेलिंग के तौर पर दिखाने की कोशिश करता है. address प्रॉपर्टी के addressComponents कलेक्शन में मौजूद पता एलिमेंट, text प्रॉपर्टी में सही स्ट्रिंग दिखाता है. साथ ही, यह भी बताता है कि spellCorrected को true पर सेट करने से स्पेलिंग की गड़बड़ी हुई थी:

{
    "componentName": {
        "text": "Mountain View",
        "languageCode": "en"
    },
    "componentType": "locality",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}

पते के ऐसे कॉम्पोनेंट जो मौजूद नहीं हैं और जिनकी पुष्टि नहीं की गई है

उपयोगकर्ता इनपुट पते का कोई हिस्सा छोड़ सकते हैं. नीचे दिए गए उदाहरण में, उपयोगकर्ता सड़क का नंबर डालता है, लेकिन सड़क का नाम नहीं:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600"]
  }
}

इस मामले में, नतीजे में addressComplete प्रॉपर्टी को हटा दिया जाता है, क्योंकि एपीआई के लिए पते की समस्या हल करने के लिए ज़रूरी जानकारी मौजूद नहीं होती. एपीआई, hasUnconfirmedComponents को true पर भी सेट करता है. इससे पता चलता है कि पते में ऐसे कॉम्पोनेंट हैं जिनकी पुष्टि नहीं हुई है:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

यह भी ध्यान दें कि validationGranularity और geocodeGranularity को OTHER पर सेट किया गया है, क्योंकि एपीआई पते का इस्तेमाल नहीं कर सका.

address प्रॉपर्टी के addressComponents ऐरे में, एपीआई स्ट्रीट नंबर कॉम्पोनेंट को UNCONFIRMED_BUT_PLAUSIBLE के तौर पर मार्क करता है:

{
  "componentName": {
    "text": "1600",
    "languageCode": "en"
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
}

आखिर में, एपीआई, address प्रॉपर्टी के missingComponentTypes और unconfirmedComponentTypes अरे में, इनपुट में मौजूद कॉम्पोनेंट को शामिल करता है और ऐसे कॉम्पोनेंट की जानकारी देता है जिनकी पुष्टि नहीं की जा सकी:

"missingComponentTypes": [
  "route",
  "postal_code"
],
"unconfirmedComponentTypes": [
  "street_number"
]

विवरण के अलग-अलग मान को समझना

रिस्पॉन्स में विवरण के स्तर की वैल्यू से यह अहम जानकारी मिलती है कि एपीआई किसी पते को कितनी सटीक या कितनी सटीक तरीके से समझ सकता है. उदाहरण के लिए, नीचे दिए गए इनपुट पते का इस्तेमाल किया जाता है:

{
  "address": {
    "regionCode": "US",
    "locality": "Northampton",
    "addressLines": ["6 South Main Street APT 456"]
  }
}

इस उदाहरण में, एपीआई को यूएसपीएस डेटाबेस में स्ट्रीट नंबर तो मिलता है, लेकिन अपार्टमेंट नंबर नहीं मिलता. इसके अलावा, एपीआई को सड़क के नंबर "6" के लिए, सटीक जियोकोड नहीं मिल सका, लेकिन "4" और "8" के लिए एक सही जियोकोड मिल सकता है. इस मामले में, एपीआई यह verdict दिखाता है:

"verdict": {
    "inputGranularity": "SUB_PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE_PROXIMITY",
    "addressComplete": true,
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

इस जवाब में:

  • inputGranularity SUB_PREMISE है, क्योंकि एपीआई इनपुट पते को अपार्टमेंट लेवल पर पार्स कर सकता है. inputGranularity सिर्फ़ उन एपीआई पर लागू होता है जो इनपुट पते को पार्स करने की अनुमति देते हैं. यह पते पर की गई पुष्टि पर लागू नहीं होता है.

  • validationGranularity PREMISE है, क्योंकि एपीआई स्ट्रीट नंबर "6" की मौजूदगी की पुष्टि कर सकता है, लेकिन "APT 456" का नहीं. हालांकि, एपीआई "APT 456" की पुष्टि नहीं कर सकता, लेकिन इसे अब भी आउटपुट formattedAddress और postalAddress फ़ील्ड में शामिल किया जाता है.

  • geocodeGranularity PREMISE_PROXIMITY है, क्योंकि एपीआई सिर्फ़ जियोकोड की गई जगह का पता लगा सकता है, इनपुट के सटीक पते के लिए उसे जियोकोड नहीं कर सका.

यूएसपीएस ने आर्टिफ़िशियल तरीके से पते की पहचान की है

जब यूएसपीएस आर्टिफ़िशियल तरीके से बनाए गए किसी पते की पहचान करता है, तो रिस्पॉन्स की uspsData प्रॉपर्टी के errorMessage फ़ील्ड में, समस्या के बारे में जानकारी देने वाला गड़बड़ी का मैसेज शामिल होता है. जैसे:

"uspsData": {
    "errorMessage": "AMS API processing was terminated due to the detection of
    what is determined to be an artificially created address. No address beyond
    this point has been validated and/or processed. If you believe this address
    was identified in error, please contact your Vendor."
}

एपीआई को आर्टिफ़िशियल पते भेजने से, यूएसपीएस डेटाबेस का ऐक्सेस खो सकता है. गड़बड़ी का यह मैसेज मिलने पर, हमारा सुझाव है कि आप पते के सोर्स की जांच करें, ताकि एपीआई को और नकली पते भेजे जाने से रोका जा सके.

सुरक्षा से जुड़े इस तरीके को इसलिए बनाया गया है, ताकि पता सूची को गलत तरीके से बनने से रोका जा सके. इसके लिए, यह पता लगाया जाता है कि सबमिट किया गया पता, कब गलत तरीके से बनाया गया है और उसे सही तरीके से नहीं लिया गया है. ऐसा कभी-कभार ही होगा.