Address Validation API सेट अप करना

यूरोपियन इकनॉमिक एरिया (ईईए) के डेवलपर

इस दस्तावेज़ में, Address Validation API का इस्तेमाल शुरू करने के लिए ज़रूरी चरणों के बारे में बताया गया है.

ज़रूरी शर्तें

इस प्रोसेस में, आपको Google Cloud खाता और बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट सेट अप करने का तरीका बताया गया है. आपको यह भी पता होना चाहिए कि Address Validation API का इस्तेमाल करने पर, आपसे शुल्क कैसे लिया जाता है.

  1. Address Validation API के इस्तेमाल और बिलिंग पेज पर जाकर, एपीआई के इस्तेमाल से जुड़ी बिलिंग और लागत की समीक्षा करें.
  2. पुष्टि करें कि आपके पास Google Cloud खाता है.

    Google Cloud Console में साइन इन करना
  3. पुष्टि करें कि आपके पास बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट है.

    बिलिंग पेज पर जाएं
    1. बिलिंग पेज खोलने के लिए, अपना प्रोजेक्ट चुनें.
    2. बिलिंग पेज पर:

      • अगर चुने गए प्रोजेक्ट के लिए बिलिंग पहले से चालू है और आपके पास सिर्फ़ एक बिलिंग खाता है, तो बिलिंग पेज खुलता है.
      • अगर आपके पास एक से ज़्यादा बिलिंग खाते हैं, तो प्रोजेक्ट से जुड़े बिलिंग खाते की जानकारी देखने के लिए, लिंक किए गए बिलिंग खाते पर जाएं को चुनें.
      • अगर कोई बिलिंग खाता मौजूद है, लेकिन वह प्रोजेक्ट से नहीं जुड़ा है, तो आपको प्रोजेक्ट के साथ बिलिंग खाता लिंक करने के लिए कहा जाएगा.
      • अगर कोई बिलिंग खाता मौजूद नहीं है या आपको नया बिलिंग खाता बनाना है, तो नया बिलिंग खाता बनाने के लिए, बिलिंग खाते मैनेज करें को चुनें. ज़्यादा जानकारी के लिए, खुद से मैनेज किया जाने वाला नया Cloud Billing खाता बनाना लेख पढ़ें.

एपीआई को चालू करना

Address Validation API का इस्तेमाल करने से पहले, आपको Google Cloud console या gcloud कमांड का इस्तेमाल करके, इसे अपने Google Cloud प्रोजेक्ट में चालू करना होगा.

एपीआई को चालू करने के लिए:

कंसोल

  1. Google Cloud Console में प्रॉडक्ट पेज खोलें:

    Address Validation API को चालू करना
  2. चालू करें बटन पर क्लिक करें.

gcloud

gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com"

Google Cloud SDK, Cloud SDK को इंस्टॉल करने, और इन निर्देशों के बारे में ज़्यादा जानें:

Address Validation API के साथ इस्तेमाल करने के लिए, एपीआई पासकोड पाना

Google Maps Platform के प्रॉडक्ट को बिना अनुमति के इस्तेमाल करने से रोकने के लिए, एपीआई कॉल में एपीआई पासकोड या OAuth टोकन शामिल करना ज़रूरी है. सबसे पहले, एपीआई पासकोड जनरेट करने की प्रोसेस पूरी करनी होगी. OAuth टोकन का इस्तेमाल करने के लिए, OAuth टोकन बनाना लेख पढ़ें.

एपीआई पासकोड, अक्षरों और अंकों से बनी एक यूनीक स्ट्रिंग होती है. यह आपके Cloud बिलिंग खाते और Google Cloud प्रोजेक्ट को उस अनुरोध से जोड़ती है जो आपका ऐप्लिकेशन, Google Maps Platform API या एसडीके को भेजता है. नई कुंजी बनाने या किसी मौजूदा कुंजी में एपीआई या SDK टूल जोड़ने के लिए, यह तरीका अपनाएं.

कंसोल

  1. Google Maps Platform > कुंजियां और क्रेडेंशियल पेज पर जाएं.

    कुंजियां और क्रेडेंशियल पेज पर जाएं

  2. अगर कहा जाए, तो अपना प्रोजेक्ट चुनें.
  3. इनमें से कोई एक काम करें:

    • नई कुंजी बनाना:

      1. क्रेडेंशियल बनाएं > एपीआई पासकोड पर क्लिक करें.
      2. एपीआई पासकोड बनाएं पैनल में, एपीआई से जुड़ी पाबंदियां चुनें सूची खोलें.
      3. इस पासकोड के लिए जिन एपीआई की ज़रूरत नहीं है उन्हें हटाएं. साथ ही, पक्का करें कि Address Validation API चुना गया हो.
      4. बनाएं पर क्लिक करें. पैनल में आपका नया एपीआई पासकोड दिखता है.
    • किसी मौजूदा कुंजी का इस्तेमाल करना:

      1. कुंजी के नाम पर क्लिक करें.
      2. एपीआई से जुड़ी पाबंदियां चुनें सूची में, Address Validation API चुनें.
      3. सेव करें पर क्लिक करें.

    यहां किसी एपीआई को चुनने से वह चालू नहीं होता. पक्का करें कि Address Validation API, इसके एपीआई लाइब्रेरी पेज पर चालू हो.

  4. कुंजी की स्ट्रिंग को बाद में देखने के लिए, कुंजियां और क्रेडेंशियल पेज पर जाएं. इसके बाद, कुंजी के लिए कुंजी दिखाएं पर क्लिक करें.

अगर कंसोल इन चरणों से अलग दिखता है, तो Google Cloud के दस्तावेज़ में जाकर, एपीआई पासकोड बनाना और एपीआई से जुड़ी पाबंदियां जोड़ना लेख पढ़ें.

gcloud

यहां दिए गए कमांड में, PROJECT_ID की जगह अपना प्रोजेक्ट आईडी डालें.

  • नई कुंजी बनाएं: यहां दिया गया निर्देश चलाएं और DISPLAY_NAME को कुंजी के नाम से बदलें.

    gcloud services api-keys create \
        --project="PROJECT_ID" \
        --display-name="DISPLAY_NAME" \
        --api-target=service=addressvalidation.googleapis.com

    Google Cloud SDK, Cloud SDK को इंस्टॉल करने, और इन निर्देशों के बारे में ज़्यादा जानें:

  • किसी मौजूदा कुंजी का इस्तेमाल करना: यह कमांड चलाएं और KEY_ID को कुंजी के आईडी से बदलें. --append फ़्लैग, उन एपीआई को बनाए रखता है जिनकी अनुमति कुंजी पहले से देती है. इसके बिना, कमांड उन्हें बदल देता है.

    gcloud services api-keys update KEY_ID \
        --project="PROJECT_ID" \
        --append \
        --api-target=service=addressvalidation.googleapis.com

    Google Cloud SDK, Cloud SDK को इंस्टॉल करने, और इन निर्देशों के बारे में ज़्यादा जानें:

    कुंजी का आईडी, कुंजी की स्ट्रिंग या डिसप्ले नेम नहीं होता. इसे ढूंढने के लिए, gcloud services api-keys list --project="PROJECT_ID" चलाएं. आईडी, name फ़ील्ड का आखिरी हिस्सा होता है: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

की स्ट्रिंग देखने के लिए, gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID" चलाएं.

एपीआई अनुरोध करना

"1600 Amphitheatre Parkway, Mountain View, CA" पते की पुष्टि करने के लिए, Address Validation API का अनुरोध करें, ताकि JSON रिस्पॉन्स मिल सके. आपको हर अनुरोध के साथ, एपीआई पासकोड की अक्षरों और अंकों वाली स्ट्रिंग शामिल करनी होगी. साथ ही, एपीआई पासकोड वाले अनुरोधों के लिए एचटीटीपीएस का इस्तेमाल करना होगा.

  1. कुंजी की अक्षरों और अंकों वाली स्ट्रिंग डालने के लिए, नीचे दिए गए कोड में API_KEY पर क्लिक करें:

    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"
    
  2. curl कमांड को कॉपी करने के लिए, कोड सैंपल में मौजूद कॉपी करें आइकॉन 'कॉपी करें' आइकॉन को चुनें. पर क्लिक करें.
  3. कमांड को टर्मिनल विंडो में चिपकाएं और उसे चलाएं.

रिस्पॉन्स, इस फ़ॉर्म में एक JSON ऑब्जेक्ट होता है:

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4225022,
        "longitude": -122.0847398
      },
      "plusCode": {
        "globalCode": "849VCWF8+24"
      },
      "bounds": {
        "low": {
          "latitude": 37.4225022,
          "longitude": -122.0847398
        },
        "high": {
          "latitude": 37.4225022,
          "longitude": -122.0847398
        }
      },
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeTypes": [
        "street_address"
      ]
    },
    "metadata": {
      "business": true,
      "residential": false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S",
      "dpvNoStatReasonCode": 5,
      "dpvDrop": "N",
      "dpvThrowback": "N",
      "dpvNonDeliveryDays": "N",
      "dpvNoSecureLocation": "N",
      "dpvPbsa": "N",
      "dpvDoorNotAccessible": "N",
      "dpvEnhancedDeliveryCode": "Y"
    }
  },
  "responseId": "a3d051f9-a802-4d8a-b530-46ee45903453"
}

एपीआई पासकोड से जुड़ी पाबंदियां लागू करना

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

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

पाबंदियां लगाने के बारे में ज़्यादा जानकारी के लिए, एपीआई पासकोड पर पाबंदी लगाना लेख पढ़ें.

OAuth टोकन बनाना

Address Validation API, पुष्टि करने के लिए OAuth 2.0 के साथ काम करता है. Google, OAuth 2.0 के सामान्य मामलों के साथ काम करता है. जैसे, वेब सर्वर के मामले.

इस दस्तावेज़ में, आपके डेवलपमेंट एनवायरमेंट में Address Validation API कॉल को OAuth टोकन पास करने का तरीका बताया गया है. प्रोडक्शन एनवायरमेंट में OAuth का इस्तेमाल करने के बारे में ज़्यादा जानने के लिए, Google पर पुष्टि करने के तरीके देखें.

सर्वर को एपीआई अनुरोध भेजकर, Google Maps API को सीधे कॉल किया जा सकता है. इसके अलावा, अपने कोड को आसान बनाने के लिए, क्लाइंट लाइब्रेरी का इस्तेमाल किया जा सकता है. Google Maps, Go, Java, Node.js, और Python के लिए क्लाइंट लाइब्रेरी उपलब्ध कराता है. ज़्यादा जानकारी के लिए, Address Validation API की क्लाइंट लाइब्रेरी देखें.

OAuth के बारे में खास जानकारी

डिप्लॉयमेंट एनवायरमेंट के आधार पर, OAuth की मदद से ऐक्सेस टोकन बनाने और उन्हें मैनेज करने के कई तरीके हैं.

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

इसके अलावा, Address Validation API को Android या iOS मोबाइल ऐप्लिकेशन में इंटिग्रेट किया जा सकता है. अलग-अलग डिप्लॉयमेंट एनवायरमेंट के लिए, OAuth का इस्तेमाल करने और ऐक्सेस टोकन मैनेज करने के बारे में ज़्यादा जानने के लिए, Google API को ऐक्सेस करने के लिए OAuth 2.0 का इस्तेमाल करना लेख पढ़ें.

OAuth के दायरे

Address Validation API के साथ OAuth का इस्तेमाल करने के लिए, आपको OAuth टोकन को यह दायरा असाइन करना होगा:

https://www.googleapis.com/auth/cloud-platform

उदाहरण: अपने लोकल डेवलपमेंट एनवायरमेंट में REST API कॉल आज़माना

अगर आपके पास टोकन जनरेट करने वाला एनवायरमेंट नहीं है और आपको OAuth टोकन के साथ Address Validation API को आज़माना है, तो इस सेक्शन में दिया गया तरीका अपनाएं.

इस उदाहरण में, कॉल करने के लिए ऐप्लिकेशन डिफ़ॉल्ट क्रेडेंशियल (एडीसी) से मिले OAuth टोकन का इस्तेमाल करने का तरीका बताया गया है. क्लाइंट लाइब्रेरी की मदद से Google API को कॉल करने के लिए, एडीसी का इस्तेमाल करने के बारे में ज़्यादा जानने के लिए, क्लाइंट लाइब्रेरी का इस्तेमाल करके पुष्टि करना लेख पढ़ें.

यहां दी गई REST प्रोसेस का इस्तेमाल सिर्फ़ डेवलपमेंट या टेस्टिंग के लिए करें, प्रोडक्शन के लिए नहीं.

ज़रूरी शर्तें

एडीसी का इस्तेमाल करके REST अनुरोध करने से पहले, एडीसी को क्रेडेंशियल देने के लिए gcloud सीएलआई का इस्तेमाल करें:

  1. gcloud सीएलआई को इंस्टॉल करें और उसे शुरू करें. ज़्यादा जानकारी के लिए, gcloud सीएलआई इंस्टॉल करें लेख पढ़ें.

  2. gcloud सीएलआई की मदद से पुष्टि करें:

    gcloud auth application-default login
  3. एडीसी की इस्तेमाल की जाने वाली लोकल क्रेडेंशियल फ़ाइल में अपने क्रेडेंशियल सेव करने के लिए, साइन इन करने की प्रोसेस पूरी करें.

ज़्यादा जानकारी के लिए, लोकल डेवलपमेंट एनवायरमेंट के लिए एडीसी सेट अप करना लेख पढ़ें.

REST अनुरोध करना

इस उदाहरण में, आप दो अनुरोध का हेडर पास करते हैं:

  • टोकन जनरेट करने के लिए, इस कमांड का इस्तेमाल करके Authorization हेडर में OAuth टोकन पास करें:

    gcloud auth application-default print-access-token

    वापस किए गए टोकन का दायरा https://www.googleapis.com/auth/cloud-platform है.

  • अपने उस Google Cloud प्रोजेक्ट का आईडी या नाम पास करें जिसके लिए X-Goog-User-Project हेडर में बिलिंग की सुविधा चालू है.

OAuth टोकन का इस्तेमाल करके Address Validation API को कॉल करने के लिए, यह तरीका अपनाएं:

  1. यहां दिए गए कोड सैंपल में, PROJECT_ID की जगह अपना Google Cloud प्रोजेक्ट आईडी डालें:

    curl -X POST -d '{
    "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600 Amphitheatre Pkwy"]
    }
    }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://addressvalidation.googleapis.com/v1:validateAddress"
    
  2. curl कमांड को कॉपी करने के लिए, कोड सैंपल में कॉपी करें पर क्लिक करें.

  3. कमांड को टर्मिनल विंडो में चिपकाएं और फिर उसे चलाएं.

रिस्पॉन्स, एक JSON ऑब्जेक्ट है:

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4225022,
        "longitude": -122.0847398
      },
      "plusCode": {
        "globalCode": "849VCWF8+24"
      },
      "bounds": {
        "low": {
          "latitude": 37.4225022,
          "longitude": -122.0847398
        },
        "high": {
          "latitude": 37.4225022,
          "longitude": -122.0847398
        }
      },
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeTypes": [
        "street_address"
      ]
    },
    "metadata": {
      "business": true,
      "residential": false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S",
      "dpvNoStatReasonCode": 5,
      "dpvDrop": "N",
      "dpvThrowback": "N",
      "dpvNonDeliveryDays": "N",
      "dpvNoSecureLocation": "N",
      "dpvPbsa": "N",
      "dpvDoorNotAccessible": "N",
      "dpvEnhancedDeliveryCode": "Y"
    }
  },
  "responseId": "fac2ae1b-50ce-442c-8bc3-d459039950ef"
}

समस्या का हल

अगर आपके अनुरोध पर गड़बड़ी का यह मैसेज मिलता है कि यह एपीआई असली उपयोगकर्ता के क्रेडेंशियल के साथ काम नहीं करता, तो एडीसी सेटअप से जुड़ी समस्या हल करना लेख पढ़ें.

आगे क्या करना है

Address Validation API को चालू करने और अनुरोध करने के बाद, एपीआई को इस्तेमाल करने के बारे में ज़्यादा जानने के लिए, पते की पुष्टि करने का अनुरोध भेजें और पते की पुष्टि करने के बुनियादी जवाब को समझें लेख पढ़ें.