किसी पते का जियोकोड पाना

जियोकोडिंग की मदद से, किसी पते को मैप पर मौजूद जगह में बदला जाता है. किसी पते को जियोकोड करने पर, जवाब में यह जानकारी शामिल होती है:

• जगह का आईडी
• जगह के अक्षांश और देशांतर के कोऑर्डिनेट
• जगह का प्लस कोड
• पते की ज़्यादा जानकारी

जियोकोड का अनुरोध

जियोकोड अनुरोध एक एचटीटीपी GET अनुरोध होता है. पते को अनस्ट्रक्चर्ड स्ट्रिंग के तौर पर दिखाया जा सकता है:

https://geocode.googleapis.com/v4beta/geocode/address/ADDRESS_STRING

या पते के कॉम्पोनेंट के स्ट्रक्चर्ड सेट के तौर पर क्वेरी पैरामीटर के ज़रिए दिखाया गया है:

https://geocode.googleapis.com/v4beta/geocode/address?STRUCTURED_ADDRESS

आम तौर पर, एचटीएमएल फ़ॉर्म में कैप्चर किए गए पते के कॉम्पोनेंट को प्रोसेस करते समय, स्ट्रक्चर्ड फ़ॉर्मैट का इस्तेमाल किया जाता है.

अन्य सभी पैरामीटर को यूआरएल पैरामीटर के तौर पर पास करें. इसके अलावा, एपीआई कुंजी और फ़ील्ड मास्क जैसे पैरामीटर के लिए, GET अनुरोध के हिस्से के तौर पर हेडर में पास करें.

अनस्ट्रक्चर्ड पते की स्ट्रिंग पास करें

अनस्ट्रक्चर्ड पता, स्ट्रिंग या प्लस कोड के तौर पर फ़ॉर्मैट किया गया पता होता है. उदाहरण के लिए, यहां दिए गए उदाहरण में यूआरएल के तौर पर कोड की गई पता स्ट्रिंग "1600 Amphitheatre Parkway, Mountain View, CA" पास की गई है:

https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

ध्यान दें कि यूआरएल में मौजूद "+" वर्ण को स्पेस में बदल दिया गया है.

curl कमांड का इस्तेमाल करके भी अनुरोध किया जा सकता है:

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

पतों में कई तरह के खास वर्ण शामिल किए जा सकते हैं. उदाहरण के लिए, "/" जैसा कि "7/1 King St, Concord West" में है. "/" को %2F के तौर पर यूआरएल कोड में बदलें:

https://geocode.googleapis.com/v4beta/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

एक और सामान्य उदाहरण "#" वर्ण है, जैसा कि "9500 W Bryn Mawr Ave #650, Rosemont" में है. "#" को %2FE के तौर पर यूआरएल कोड में बदलें:

https://geocode.googleapis.com/v4beta/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

अगले उदाहरण में, आपने बिना किसी स्ट्रक्चर वाली पते की स्ट्रिंग को प्लस कोड 849VCWC8+R4 के तौर पर तय किया है. पक्का करें कि आपने "+" वर्ण को यूआरएल कोड में %2B के तौर पर बदला हो:

https://geocode.googleapis.com/v4beta/geocode/address/849VCWC8%2BR4?key=API_KEY

स्ट्रक्चर्ड पता पास करना

PostalAddress टाइप के address क्वेरी पैरामीटर का इस्तेमाल करके, कारोबार की जगह का पूरा पता बताएं. PostalAddress ऑब्जेक्ट की मदद से, अनुरोध में पते के कुछ या सभी कॉम्पोनेंट को अलग-अलग क्वेरी पैरामीटर के तौर पर सेट किया जा सकता है.

उदाहरण के लिए, इस्तेमाल किए गए पते का सिर्फ़ पिन कोड डालने के लिए PostalAddress.postalCode:

https://geocode.googleapis.com/v4beta/geocode/address?address.postalCode=01062&key=API_KEY

एक से ज़्यादा पते के कॉम्पोनेंट के बारे में जानकारी देने के लिए, एक से ज़्यादा क्वेरी पैरामीटर का इस्तेमाल करें. जैसे, एचटीएमएल फ़ॉर्म में कैप्चर किए गए पते के कॉम्पोनेंट के लिए:

https://geocode.googleapis.com/v4beta/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&key=API_KEY

अनुरोध करने के लिए OAuth का इस्तेमाल करना

Geocoding API v4, पुष्टि करने के लिए OAuth 2.0 का इस्तेमाल करता है. Geocoding API के साथ OAuth का इस्तेमाल करने के लिए, OAuth टोकन को सही स्कोप असाइन किया जाना चाहिए. Geocoding API, फ़ॉरवर्ड जियोकोडिंग के साथ इस्तेमाल करने के लिए इन स्कोप के साथ काम करता है:

• https://www.googleapis.com/auth/maps-platform.geocode — इसका इस्तेमाल Geocoding API के सभी एंडपॉइंट के साथ किया जाता है.
• https://www.googleapis.com/auth/maps-platform.geocode.address — इसका इस्तेमाल सिर्फ़ GeocodeAddress के साथ किया जाता है, ताकि आगे की जियोकोडिंग की जा सके.

इसके अलावा, सभी Geocoding API एंडपॉइंट के लिए, सामान्य https://www.googleapis.com/auth/cloud-platform स्कोप का इस्तेमाल किया जा सकता है. यह स्कोप डेवलपमेंट के दौरान काम आता है, लेकिन प्रोडक्शन के दौरान नहीं. ऐसा इसलिए, क्योंकि यह एक सामान्य स्कोप है, जो सभी एंडपॉइंट को ऐक्सेस करने की अनुमति देता है.

ज़्यादा जानकारी और उदाहरणों के लिए, OAuth का इस्तेमाल करना लेख पढ़ें.

जियोकोड रिस्पॉन्स

जियोकोडिंग, GeocodeAddressResponse ऑब्जेक्ट दिखाता है. इसमें GeocodeResult ऑब्जेक्ट का results कलेक्शन होता है. हर GeocodeResult ऑब्जेक्ट, किसी एक जगह के बारे में बताता है.

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

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

ज़रूरी पैरामीटर

• address — वह सड़क का पता या प्लस कोड जिसे आपको जियोकोड करना है. पते, उस देश की राष्ट्रीय डाक सेवा के इस्तेमाल किए गए फ़ॉर्मैट के मुताबिक होने चाहिए. पते में कारोबार का नाम, यूनिट, सुइट या फ़्लोर नंबर जैसी अतिरिक्त जानकारी नहीं होनी चाहिए. सड़क के पते के एलिमेंट को स्पेस से अलग किया जाना चाहिए. साथ ही, यूआरएल के लिए कोड में बदलकर %20 किया जाना चाहिए. उदाहरण के लिए, "24 Sussex Drive Ottawa ON" पते को इस तरह पास करें:

  24%20Sussex%20Drive%20Ottawa%20ON

  Plus Code को यहां दिखाए गए तरीके से फ़ॉर्मैट करें. प्लस के निशान को यूआरएल के लिए कोड में बदलकर %2B लिखा जाता है और स्पेस को यूआरएल के लिए कोड में बदलकर %20 लिखा जाता है:
  • ग्लोबल कोड में चार वर्णों का एरिया कोड और छह या इससे ज़्यादा वर्णों का लोकल कोड होता है. उदाहरण के लिए, "849VCWC8+R9" को 849VCWC8%2BR9 के तौर पर कोड में बदलें.
  • कंपाउंड कोड, छह या इससे ज़्यादा वर्णों का लोकल कोड होता है. इसमें जगह की जानकारी साफ़ तौर पर दी गई होती है. उदाहरण के लिए, "CWC8+R9 Mountain View, CA, USA" को CWC8%2BR9%20Mountain%20View%20CA%20USA के तौर पर कोड करें.

ज़रूरी नहीं पैरामीटर

• locationBias

  यह Viewport के तौर पर, खोज के लिए कोई इलाका तय करता है. यह जगह, खोज के नतीजों को प्रभावित करती है. इसका मतलब है कि बताई गई जगह के आस-पास के नतीजे दिखाए जा सकते हैं. इनमें उस जगह के आस-पास के नतीजे भी शामिल हैं जो उस जगह के दायरे में नहीं आते.

  रीजन को आयत के आकार वाले व्यूपोर्ट के तौर पर सेट करें. आयत, अक्षांश-देशांतर का व्यूपोर्ट होता है. इसे दो विकर्ण विपरीत बिंदुओं के तौर पर दिखाया जाता है. लो पॉइंट, आयत के दक्षिण-पश्चिम कोने को दिखाता है. वहीं, हाई पॉइंट, आयत के उत्तर-पूर्व कोने को दिखाता है.

  व्यूपोर्ट को एक बंद क्षेत्र माना जाता है. इसका मतलब है कि इसमें इसकी सीमा शामिल होती है. अक्षांश की सीमाएं -90 से 90 डिग्री के बीच होनी चाहिए. इसमें ये दोनों वैल्यू शामिल हैं. साथ ही, देशांतर की सीमाएं -180 से 180 डिग्री के बीच होनी चाहिए. इसमें ये दोनों वैल्यू शामिल हैं:

  • अगर low = high है, तो व्यूपोर्ट में सिर्फ़ एक पॉइंट होता है.
  • अगर low.longitude > high.longitude है, तो देशांतर की रेंज उल्टी हो जाती है. इसका मतलब है कि व्यूपोर्ट, 180 डिग्री देशांतर वाली लाइन को पार कर जाता है.
  • अगर low.longitude = -180 डिग्री और high.longitude = 180 डिग्री है, तो व्यूपोर्ट में सभी देशांतर शामिल होते हैं.
  • अगर low.longitude = 180 डिग्री और high.longitude = -180 डिग्री है, तो देशांतर की सीमा खाली होती है.
  • अगर low.latitude > high.latitude है, तो अक्षांश की रेंज खाली होती है.

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

  उदाहरण के लिए, यह क्वेरी स्ट्रिंग ऐसे व्यूपोर्ट को तय करती है जिसमें पूरा न्यूयॉर्क शहर शामिल है:

  ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

• languageCode

  वह भाषा जिसमें नतीजे दिखाने हैं.

  • इस्तेमाल की जा सकने वाली भाषाओं की सूची देखें. Google, अक्सर उन भाषाओं को अपडेट करता है जिनमें Gemini का इस्तेमाल किया जा सकता है. इसलिए, हो सकता है कि इस सूची में पूरी जानकारी शामिल न हो.
  • अगर languageCode नहीं दिया गया है, तो एपीआई डिफ़ॉल्ट रूप से en पर सेट हो जाता है. अगर आपने अमान्य भाषा कोड डाला है, तो एपीआई INVALID_ARGUMENT गड़बड़ी का मैसेज दिखाता है.
  • एपीआई, मोहल्ले का ऐसा पता देने की पूरी कोशिश करता है जिसे उपयोगकर्ता और स्थानीय लोग, दोनों पढ़ सकें. इस लक्ष्य को पूरा करने के लिए, यह स्थानीय भाषा में सड़क के पते दिखाता है. अगर ज़रूरी हो, तो यह पते को ऐसी स्क्रिप्ट में लिप्यंतरित करता है जिसे उपयोगकर्ता पढ़ सकता है. ऐसा करते समय, यह उपयोगकर्ता की पसंदीदा भाषा का ध्यान रखता है. अन्य सभी पते, चुनी गई भाषा में दिखाए जाते हैं. पते के सभी कॉम्पोनेंट, एक ही भाषा में दिखाए जाते हैं. यह भाषा, पहले कॉम्पोनेंट से चुनी जाती है.
  • अगर नाम आपकी पसंदीदा भाषा में उपलब्ध नहीं है, तो एपीआई सबसे मिलते-जुलते नाम का इस्तेमाल करता है.
  • पसंदीदा भाषा का असर, एपीआई से मिले नतीजों के सेट और उनके क्रम पर पड़ता है. जियोकोडर, भाषा के हिसाब से शॉर्ट फ़ॉर्म का अलग-अलग मतलब निकालता है. जैसे, सड़क के टाइप के लिए इस्तेमाल किए गए शॉर्ट फ़ॉर्म या ऐसे समानार्थी शब्द जो एक भाषा में मान्य हो सकते हैं, लेकिन दूसरी भाषा में नहीं.

• regionCode

  देश/इलाके का कोड, दो वर्णों वाले CLDR कोड की वैल्यू के तौर पर. कोई डिफ़ॉल्ट वैल्यू नहीं है. ज़्यादातर CLDR कोड, ISO 3166-1 कोड के जैसे ही होते हैं.

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

जगह की जानकारी के आधार पर नतीजे दिखाना

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

उदाहरण के लिए, "वॉशिंगटन" पते के लिए जियोकोड का अनुरोध करने पर, वॉशिंगटन डी॰सी॰ और अमेरिका के वॉशिंगटन राज्य, दोनों के नतीजे मिल सकते हैं:

https://geocode.googleapis.com/v4beta/geocode/address/Washington?key=API_KEY

जवाब इस फ़ॉर्म में है:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

हालांकि, अमेरिका के उत्तर-पूर्वी हिस्से के चारों ओर बाउंडिंग बॉक्स तय करने वाला locationBias पैरामीटर जोड़ने पर, इस जियोकोड से सिर्फ़ वॉशिंगटन, डीसी शहर की जानकारी मिलती है:

https://geocode.googleapis.com/v4beta/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

क्षेत्र के हिसाब से प्राथमिकता देना

जियोकोडिंग के अनुरोध में, regionCode पैरामीटर का इस्तेमाल करके, Geocoding सेवा को किसी खास इलाके के हिसाब से नतीजे दिखाने के लिए कहा जा सकता है. इस पैरामीटर में, दो वर्णों वाला CLDR कोड वैल्यू दी जाती है. इससे क्षेत्र के हिसाब से खोज के नतीजों में बदलाव होता है. ज़्यादातर CLDR कोड, ISO 3166-1 कोड के जैसे ही होते हैं.

regionCode एट्रिब्यूट की कोई डिफ़ॉल्ट वैल्यू नहीं होती. उदाहरण के लिए, "Toledo" के जियोकोड से, अमेरिका और स्पेन के नतीजे मिलते हैं:

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?key=API_KEY

जवाब:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

सिर्फ़ regionCode=es (स्पेन) के लिए "टॉलेडो" की जियोकोडिंग के अनुरोध से, सिर्फ़ स्पेन के नतीजे मिलते हैं:

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY