किसी जगह को जियोकोड में बदलना

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

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

• पते का जगह का आईडी
• पते के Plus Codes
• पता

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

रिवर्स जियोकोडिंग का अनुरोध

रिवर्स जियोकोडिंग का अनुरोध, एचटीटीपी GET अनुरोध होता है. जगह की जानकारी को, बिना किसी फ़ॉर्मैट वाली स्ट्रिंग के तौर पर दिया जा सकता है:

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

इसके अलावा, क्वेरी पैरामीटर के तौर पर, अक्षांश और देशांतर निर्देशांकों के स्ट्रक्चर्ड सेट के तौर पर भी दिया जा सकता है:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

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

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

बिना किसी फ़ॉर्मैट वाली जगह की जानकारी वाली स्ट्रिंग पास करना

बिना किसी फ़ॉर्मैट वाली जगह की जानकारी, अक्षांश और देशांतर निर्देशांकों की कॉमा लगाकर अलग किए गए स्ट्रिंग के तौर पर फ़ॉर्मैट की गई जगह होती है:

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=API_KEY

या curl कमांड में:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"

स्ट्रक्चर्ड जगह की जानकारी पास करना

स्ट्रक्चर्ड जगह की जानकारी देने के लिए, location क्वेरी पैरामीटर का इस्तेमाल करें, जिसका टाइप है LatLng. LatLng ऑब्जेक्ट की मदद से, अक्षांश और देशांतर को अलग-अलग क्वेरी पैरामीटर के तौर पर तय किया जा सकता है:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

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

Geocoding API का चौथा वर्शन, पुष्टि करने के लिए 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.location — रिवर्स जियोकोडिंग के लिए, सिर्फ़ GeocodeLocation के साथ इसका इस्तेमाल करें.

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

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

रिवर्स जियोकोडिंग का जवाब

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

• ऑब्जेक्ट GeocodeResult का results कलेक्शन, जो जगह की जानकारी दिखाता है.

  Geocoding API के जवाबों में, types कलेक्शन GeocodeResult में दो मुख्य जगहों पर शामिल होते हैं:

  1. GeocodeResult.types: यह कलेक्शन, नतीजे के कुल टाइप(टाइपों) के बारे में बताता है. संभावित वैल्यू, Places API में इस्तेमाल किए जाने वाले जगह के टाइप से ली जाती हैं. ज़्यादा जानकारी के लिए, जगह के टाइप की टेबल A और B देखें.
  2. GeocodeResult.addressComponents[].types: हर पते के कॉम्पोनेंट में एक types कलेक्शन होता है. इससे, पते के उस खास हिस्से के टाइप के बारे में पता चलता है. ये वैल्यू, Places API में इस्तेमाल किए जाने वाले पते के टाइप और पते के कॉम्पोनेंट के टाइप की टेबल से ली जाती हैं.

  रिवर्स जियोकोडर, results कलेक्शन में एक से ज़्यादा नतीजे दिखाता है. ये नतीजे, सिर्फ़ डाक पते नहीं होते, बल्कि किसी जगह को भौगोलिक तौर पर नाम देने का कोई भी तरीका हो सकता है. उदाहरण के लिए, शिकागो शहर में किसी पॉइंट की जियोकोडिंग करने पर, जियोकोड किए गए पॉइंट को गली के पते, शहर (शिकागो), राज्य (इलिनॉय) या देश (अमेरिका) के तौर पर दिखाया जा सकता है. जियोकोडर के लिए, ये सभी "पते" हैं. रिवर्स जियोकोडर, इनमें से किसी भी टाइप को मान्य नतीजों के तौर पर दिखाता है.

• plusCode फ़ील्ड, PlusCode टाइप का होता है. इसमें वह Plus Code होता है जो अनुरोध में दिए गए अक्षांश और देशांतर के सबसे करीब होता है. इसके अलावा, results कलेक्शन के हर एलिमेंट में एक Plus Code होता है. डिकोड किए गए Plus Code और अनुरोध में दिए गए पॉइंट के बीच की दूरी 10 मीटर से कम होती है.

  ध्यान दें: एपीआई, हमेशा Plus Codes नहीं दिखाता.

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

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "establishment",
        "point_of_interest"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

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

• जगह

  अक्षांश और देशांतर निर्देशांक, जिनसे यह तय होता है कि आपको सबसे नज़दीकी, आसानी से पढ़े जा सकने वाला पता कहां चाहिए.

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

• languageCode

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

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

• regionCode

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

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

• कंट्रोल के चुने गए लेवल

  जगह की जानकारी के एक या उससे ज़्यादा लेवल, जिन्हें Granularity के हिसाब से, अलग-अलग क्वेरी पैरामीटर के तौर पर तय किया गया है. अगर एक से ज़्यादा granularity पैरामीटर तय किए जाते हैं, तो एपीआई, उन सभी पतों को दिखाता है जो किसी भी लेवल से मैच करते हैं.

  granularity पैरामीटर, खोज को तय किए गए लेवल तक सीमित नहीं करता. इसके बजाय, granularity खोज के बाद के फ़िल्टर के तौर पर काम करता है. एपीआई, तय की गई location के लिए सभी नतीजे फ़ेच करता है. इसके बाद, उन नतीजों को हटा देता है जो तय किए गए लेवल से मैच नहीं करते.

  अगर types और granularity, दोनों तय किए जाते हैं, तो एपीआई सिर्फ़ उन नतीजों को दिखाता है जो दोनों से मैच करते हैं. उदाहरण के लिए:

  https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

• प्रकार

  पते के एक या उससे ज़्यादा टाइप, जिन्हें अलग-अलग क्वेरी पैरामीटर के तौर पर तय किया गया है. संभावित वैल्यू, जगह के टाइप (नया) पेज पर मौजूद, पते के टाइप और पते के कॉम्पोनेंट के टाइप की टेबल से ली जाती हैं. अगर एक से ज़्यादा types पैरामीटर तय किए जाते हैं, तो एपीआई, उन सभी पतों को दिखाता है जो किसी भी टाइप से मैच करते हैं.

  types पैरामीटर, खोज को तय किए गए पते के टाइप(टाइपों) तक सीमित नहीं करता. इसके बजाय, types खोज के बाद के फ़िल्टर के तौर पर काम करता है. एपीआई, तय की गई जगह के लिए सभी नतीजे फ़ेच करता है. इसके बाद, उन नतीजों को हटा देता है जो तय किए गए पते के टाइप(टाइपों) से मैच नहीं करते.

  अगर types और granularity, दोनों तय किए जाते हैं, तो एपीआई सिर्फ़ उन नतीजों को दिखाता है जो दोनों से मैच करते हैं. उदाहरण के लिए:

  https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

• FieldMask

  जवाब में दिखाए जाने वाले फ़ील्ड तय करने के लिए, जवाब का फ़ील्ड मास्क बनाएं. यूआरएल पैरामीटर $fields या fields का इस्तेमाल करके या एचटीटीपी हेडर X-Goog-FieldMask का इस्तेमाल करके, जवाब का फ़ील्ड मास्क, तरीके में पास करें. उदाहरण के लिए, नीचे दिए गए अनुरोध से, जवाब के सिर्फ़ placeID फ़ील्ड दिखेंगे.

  curl -X GET -H 'Content-Type: application/json' \
  -H 'X-Goog-FieldMask: results.placeId' \
  -H "X-Goog-Api-Key: API_KEY" \
  "https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
  

  जवाब यह है:

  {
    "results": [
      {
        "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
      },
      {
        "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
      },
      {
        "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
      },
      {
        "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
      },
      ...
    ]
  }

  ज़्यादा जानकारी के लिए, दिखाए जाने वाले फ़ील्ड चुनना लेख पढ़ें.