Geocoding v3 से v4 पर माइग्रेट करना

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

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

नए v4 के तरीकों के साथ, अपनी मौजूदा एपीआई कुंजियों का इस्तेमाल किया जा सकता है. हालांकि, अगर आपने एपीआई के v3 वर्शन के लिए कोटा बढ़ाने का अनुरोध किया है, तो आपको नए v4 वर्शन के एपीआई के लिए भी कोटा बढ़ाने का अनुरोध करना होगा.

देखें.

v3 Forward Geocoding से माइग्रेट करना

अगर पतों को जियोकोड करने के लिए जियोकोडिंग का इस्तेमाल किया जाता है, तो आपको v4 Geocode an address तरीके पर माइग्रेट करना चाहिए. यह GET अनुरोध स्वीकार करता है.

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

अनुरोध के पैरामीटर में बदलाव

v3 पैरामीटर v4 पैरामीटर नोट
address, components address बिना स्ट्रक्चर वाला पता (v3 address) अब यूआरएल पाथ में पास किया जाता है. कॉम्पोनेंट फ़िल्टर (v3 components) को अब address.* क्वेरी पैरामीटर के तौर पर पास किया जाता है.
bounds locationBias.rectangle नाम बदला गया; स्ट्रक्चर को ऑब्जेक्ट में बदल दिया गया.
language languageCode नाम बदला गया.
region regionCode नाम बदला गया.
extra_computations हटा दिया गया

जवाब वाले फ़ील्ड में बदलाव

v3 फ़ील्ड v4 फ़ील्ड नोट
status, error_message हटा दिया गया v4, एचटीटीपी स्टेटस कोड और गड़बड़ी की जानकारी का इस्तेमाल करता है.
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText नाम बदला गया.
results.geometry.location_type results.granularity नाम बदला गया.
results.geometry.location results.location फ़ील्ड के नाम: lat/lng -> latitude/longitude.
results.geometry.viewport results.viewport फ़ील्ड के नाम: northeast/southwest -> high/low.
results.postcode_localities results.postalCodeLocalities नाम बदला गया. अब एक या उससे ज़्यादा इलाकों के लिए उपलब्ध है (v3 के लिए >1 ज़रूरी है).
results.partial_match हटा दिया गया
नया results.addressComponents.languageCode पते के किसी कॉम्पोनेंट की भाषा.
नया results.bounds high/low का इस्तेमाल करके, साफ़ तौर पर सीमाएं तय करना.
नया results.place जगह का संसाधन नाम.
नया results.postalAddress स्ट्रक्चर्ड PostalAddress ऑब्जेक्ट.

v3 रिवर्स जियोकोडिंग से माइग्रेट करना

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

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

अनुरोध के पैरामीटर में बदलाव

v3 पैरामीटर v4 पैरामीटर नोट
language languageCode नाम बदला गया.
region regionCode नाम बदला गया.
result_type types नाम बदला गया; इसमें बार-बार इस्तेमाल किए गए क्वेरी पैरामीटर का इस्तेमाल किया जाता है.
location_type granularity नाम बदला गया; इसमें बार-बार इस्तेमाल किए गए क्वेरी पैरामीटर का इस्तेमाल किया जाता है.
extra_computations हटा दिया गया

जवाब वाले फ़ील्ड में बदलाव

v3 फ़ील्ड v4 फ़ील्ड नोट
status, error_message हटा दिया गया v4, एचटीटीपी स्टेटस कोड और गड़बड़ी की जानकारी का इस्तेमाल करता है.
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText नाम बदला गया.
results.geometry.location_type results.granularity नाम बदला गया.
results.geometry.location results.location फ़ील्ड के नाम: lat/lng -> latitude/longitude.
results.geometry.viewport results.viewport फ़ील्ड के नाम: northeast/southwest -> high/low.
नया results.addressComponents.languageCode पते के किसी कॉम्पोनेंट की भाषा.
नया results.bounds high/low का इस्तेमाल करके, साफ़ तौर पर सीमाएं तय करना.
नया results.place जगह का संसाधन नाम.
नया results.postalAddress स्ट्रक्चर्ड PostalAddress ऑब्जेक्ट.

Place Geocoding v3 से माइग्रेट करना

अगर आपको Geocoding v3 की मदद से किसी Place ID का पता पाना है, तो आपको v4 के Place Geocoding तरीके पर माइग्रेट करना होगा. यह तरीका, GET अनुरोध स्वीकार करता है.place_id

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

अनुरोध के पैरामीटर में बदलाव

v3 पैरामीटर v4 पैरामीटर नोट
place_id अनुरोध प्रोटो में place फ़ील्ड अब Place ID को पाथ पैरामीटर places/{place} के तौर पर दिया जाता है. उदाहरण के लिए: https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. यह अनुरोध में मौजूद जगह फ़ील्ड पर मैप होता है.
language languageCode नाम बदला गया.
region regionCode नाम बदला गया.

जवाब वाले फ़ील्ड में बदलाव

v3 फ़ील्ड v4 फ़ील्ड नोट
status, error_message हटा दिया गया v4, एचटीटीपी स्टेटस कोड और गड़बड़ी की जानकारी का इस्तेमाल करता है.
results (रूट) v4, results कलेक्शन नहीं, बल्कि एक नतीजा ऑब्जेक्ट दिखाता है.
results.address_components.long_name / results.address_components.short_name addressComponents.longText / addressComponents.shortText नाम बदला गया.
results.geometry.location_type granularity नाम बदला गया.
results.geometry.location location फ़ील्ड के नाम: lat/lng -> latitude/longitude.
results.geometry.viewport viewport फ़ील्ड के नाम: northeast/southwest -> high/low.
results.postcode_localities postalCodeLocalities नाम बदला गया. अब एक या उससे ज़्यादा इलाकों के लिए उपलब्ध है (v3 के लिए >1 ज़रूरी है).
नया addressComponents.languageCode पते के किसी कॉम्पोनेंट की भाषा.
नया bounds high/low का इस्तेमाल करके, साफ़ तौर पर सीमाएं तय करना.
नया place जगह का संसाधन नाम.
नया postalAddress स्ट्रक्चर्ड PostalAddress ऑब्जेक्ट.

जियोकोडिंग हाइपरलोकल डेटा को डेस्टिनेशन पर माइग्रेट करना

Geocoding API v3 की इन सुविधाओं को, Geocoding API v4 के SearchDestinations तरीके से बदला जा रहा है:

  • एंट्रेंस
  • नेविगेशन पॉइंट
  • बिल्डिंग की आउटलाइन
  • मैदान

अगर ऊपर दी गई सुविधाओं के लिए Geocoding API v3 का इस्तेमाल किया जा रहा था, तो इन सुविधाओं को पाने के लिए SearchDestinations तरीके का इस्तेमाल करने के लिए, यह दस्तावेज़ पढ़ें. इस दस्तावेज़ में बताया गया है कि SearchDestinations के जवाब में इन सुविधाओं को कहां ढूंढें. साथ ही, Geocoding API v3 और Geocoding API v4 के SearchDestinations तरीके के बीच, एपीआई के जवाबों में इन सुविधाओं को दिखाने के तरीके में अंतर के बारे में भी बताया गया है.

एंट्रेंस

destination से जुड़े एंट्री पॉइंट पाने के लिए, destination.entrances फ़ील्ड का इस्तेमाल करें.

ध्यान दें कि entrance का फ़ॉर्मैट, Geocoding API v3 में मौजूद एंट्रेंस फ़ॉर्मैट से थोड़ा अलग होता है. destination.entrances में मौजूद हर एंट्री में ये फ़ील्ड होते हैं:

  • displayName - यह एक नया वैकल्पिक फ़ील्ड है. इसमें प्रवेश द्वार का नाम होगा, ताकि लोग उसे आसानी से समझ सकें. उदाहरण के लिए, "गेट बी".
  • location - यह LatLng टाइप की जगह है. यह Geocoding API v3 में इस्तेमाल किए गए फ़ॉर्मैट से अलग है.
  • tags - यह Geocoding API v3 के एंट्री पॉइंट के tags फ़ील्ड के जैसा ही है.
  • place - यह Geocoding API v3 के buildingPlaceId फ़ील्ड के जैसा है. हालांकि, इस फ़ील्ड में मौजूद जगह का आईडी, किसी भी तरह की जगह का हो सकता है. यह ज़रूरी नहीं कि वह सिर्फ़ किसी इमारत का हो.

किसी destination से जुड़े नेविगेशन पॉइंट पाने के लिए, destination.navigationPoints फ़ील्ड का इस्तेमाल करें.

ध्यान दें कि navigationPoint का फ़ॉर्मैट, Geocoding API v3 में नेविगेशन पॉइंट के फ़ॉर्मैट से थोड़ा अलग होता है. destination.navigationPoints में मौजूद हर नेविगेशन पॉइंट में ये फ़ील्ड होते हैं:

  • displayName - यह एक नया वैकल्पिक फ़ील्ड है. इसमें नेविगेशन पॉइंट का ऐसा नाम होगा जिसे आसानी से पढ़ा जा सके. उदाहरण के लिए, "पांचवीं एवेन्यू".
  • location - यह LatLng टाइप की जगह है. यह Geocoding API v3 में इस्तेमाल किए गए फ़ॉर्मैट से अलग है.
  • travelModes - यह Geocoding API v3 के नेविगेशन पॉइंट के restrictedTravelModes फ़ील्ड जैसा ही है. इनकी एनम वैल्यू एक जैसी हैं. सिर्फ़ यह अंतर है कि यह फ़ील्ड अब यात्रा के उन तरीकों को दिखाता है जिन्हें नेविगेशन पॉइंट के लिए इस्तेमाल किया जा सकता है. पहले यह यात्रा के उन तरीकों को दिखाता था जिन्हें इस्तेमाल नहीं किया जा सकता.
  • usage - यह एक नया फ़ील्ड है. इसमें नेविगेशन पॉइंट के साथ काम करने वाले इस्तेमाल के उदाहरण शामिल होते हैं. ध्यान दें कि ज़्यादातर नेविगेशन पॉइंट में UNKNOWN का इस्तेमाल किया जाएगा. हालांकि, इसका यह मतलब नहीं है कि नेविगेशन पॉइंट के इस्तेमाल पर किसी तरह की पाबंदी है.

बिल्डिंग की आउटलाइन

destination से जुड़ी बिल्डिंग की आउटलाइन पाने के लिए, आपको destination में मौजूद उन placeView ऑब्जेक्ट के displayPolygon फ़ील्ड का इस्तेमाल करना चाहिए जो बिल्डिंग को दिखाते हैं. हर placeView के लिए, यह देखा जा सकता है कि वह placeView.structureType फ़ील्ड वाली बिल्डिंग है या नहीं. अगर स्ट्रक्चर टाइप BUILDING है, तो आपको आउटलाइन placeView.displayPolygon फ़ील्ड से मिल सकती है. placeView में बिल्डिंग के लिए अतिरिक्त फ़ील्ड भी होंगे, जो Geocoding API v3 में नहीं थे.

destination में placeView ऑब्जेक्ट हो सकता है. यह ऑब्जेक्ट, इन फ़ील्ड में मौजूद किसी बिल्डिंग को दिखाता है:

  • destination.primary - यह डेस्टिनेशन की मुख्य जगह है.
  • destination.containingPlaces - यह दोहराया गया फ़ील्ड है. इसमें ऐसी बड़ी जगहें शामिल हो सकती हैं जिनमें मुख्य जगह "शामिल" है. उदाहरण के लिए, अगर मुख्य जगह subpremise है, तो containingPlaces में आम तौर पर placeView होता है, जो बिल्डिंग को दिखाता है.
  • destination.subDestinations - यह दोहराया गया फ़ील्ड है, जिसमें मुख्य जगह की उप-जगहों की जानकारी शामिल की जा सकती है. उदाहरण के लिए, किसी बिल्डिंग के अलग-अलग अपार्टमेंट यूनिट. इस फ़ील्ड में आम तौर पर, placeView नहीं होता है.

ध्यान दें कि placeView.displayPolygon का फ़ॉर्मैट, Geocoding API v3 में मौजूद बिल्डिंग के आउटलाइन फ़ॉर्मैट से मेल खाता है. यह RFC 7946 फ़ॉर्मैट का इस्तेमाल करने वाला GeoJSON फ़ॉर्मैट है.

मैदान

आउटलाइन बनाने की तरह ही, destination से जुड़े मैदानों की जानकारी पाने के लिए, आपको destination में मौजूद placeView ऑब्जेक्ट के displayPolygon फ़ील्ड का इस्तेमाल करना चाहिए. ये ऑब्जेक्ट, मैदानों की जानकारी देते हैं. हर placeView के लिए, यह देखा जा सकता है कि यह placeView.structureType फ़ील्ड के हिसाब से सही है या नहीं. अगर स्ट्रक्चर टाइप GROUNDS है, तो आपको placeView.displayPolygon फ़ील्ड से आउटलाइन मिल सकती है. placeView में ऐसे अतिरिक्त फ़ील्ड भी होंगे जो Geocoding API v3 में नहीं थे.

destination में placeView ऑब्जेक्ट हो सकता है. यह ऑब्जेक्ट, इन फ़ील्ड में किसी ग्राउंड को दिखाता है:

  • destination.primary
  • destination.containingPlaces
  • destination.subDestinations

ध्यान दें कि placeView.displayPolygon का फ़ॉर्मैट, Geocoding API v3 में मौजूद ग्राउंड आउटलाइन फ़ॉर्मैट से मेल खाता है. यह RFC 7946 फ़ॉर्मैट का इस्तेमाल करने वाला GeoJSON फ़ॉर्मैट है.

इन सुविधाओं का अनुरोध करने के लिए, फ़ील्ड मास्क का इस्तेमाल करना

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

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4beta/geocode/destinations

सुरक्षा से जुड़ी बातें

Geocoding API v4 को सर्वर-टू-सर्वर एपीआई के तौर पर डिज़ाइन किया गया है. JavaScript का इस्तेमाल करने वाले लोगों के लिए, v3 से v4 पर सीधे माइग्रेट करने का कोई तरीका नहीं है. क्लाइंट-साइड JavaScript (उदाहरण के लिए, ब्राउज़र में) से सीधे तौर पर v4 के तरीकों को कॉल करने पर, आपकी एपीआई कुंजी के चोरी होने और उसके गलत इस्तेमाल का खतरा बढ़ जाता है.

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

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

क्लाइंट-साइड की ज़रूरतों के लिए विकल्प

अगर आपको क्लाइंट-साइड पर जियोकोडिंग की ज़रूरत है, तो क्लाइंट-साइड के मौजूदा समाधानों में से किसी एक का इस्तेमाल करें:

  • Maps JavaScript API में जियोकोडिंग सेवा: Geocoding Service, v3 बैकएंड का इस्तेमाल करती है. इसे ब्राउज़र एनवायरमेंट में इस्तेमाल करने के लिए डिज़ाइन किया गया है.
  • Places UI Kit: पते से जुड़े यूज़र इंटरफ़ेस एलिमेंट के लिए, Places UI Kit का इस्तेमाल करें. इसमें जगह की जानकारी अपने-आप भरने वाले एलिमेंट भी शामिल हैं.