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

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

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

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

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

अगर पतों को जियोकोड करने के लिए, जियोकोडिंग का इस्तेमाल किया जाता है, तो आपको 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 की ज़रूरत है.
results.partial_match हटा दिया गया
नया results.addressComponents.languageCode पते के किसी कॉम्पोनेंट की भाषा.
नया results.bounds high/low का इस्तेमाल करके, साफ़ तौर पर तय की गई सीमाएं.
नया results.place जगह के लिए संसाधन का नाम.
नया results.postalAddress स्ट्रक्चर्ड PostalAddress ऑब्जेक्ट.

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

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

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 ऑब्जेक्ट.

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

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

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

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

v3 पैरामीटर v4 पैरामीटर नोट
place_id अनुरोध प्रोटो में place फ़ील्ड जगह का आईडी अब पाथ पैरामीटर 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 की ज़रूरत है.
नया addressComponents.languageCode पते के किसी कॉम्पोनेंट की भाषा.
नया bounds high/low का इस्तेमाल करके, साफ़ तौर पर तय की गई सीमाएं.
नया place जगह के लिए संसाधन का नाम.
नया postalAddress स्ट्रक्चर्ड PostalAddress ऑब्जेक्ट.

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

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

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

अगर ऊपर दी गई सुविधाओं के लिए Geocoding API v3 का इस्तेमाल किया जा रहा था, तो इन सुविधाओं को पाने के लिए, SearchDestinations एंडपॉइंट का इस्तेमाल करने के लिए यह दस्तावेज़ पढ़ें. इस दस्तावेज़ में बताया गया है कि SearchDestinations API के रिस्पॉन्स में इन सुविधाओं को कहां ढूंढें. साथ ही, 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 है, तो आम तौर पर subpremise में placeView होता है, जो बिल्डिंग को दिखाता है.containingPlaces
  • 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/v4alpha/geocode/destinations