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

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

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

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

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

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

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

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

v3 पैरामीटर v4 पैरामीटर नोट
address, components address बिना स्ट्रक्चर वाला पता (v3 address) अब यूआरएल पाथ में पास किया जाता है. पते के स्ट्रक्चर्ड कॉम्पोनेंट (v3 components) को address.* क्वेरी पैरामीटर के तौर पर पास किया जा सकता है. v3 कॉम्पोनेंट फ़िल्टर फिर से जनरेट करना देखें.
bounds locationBias.rectangle नाम बदला गया; स्ट्रक्चर को ऑब्जेक्ट में बदल दिया गया.
language languageCode नाम बदला गया. अगर इसे शामिल नहीं किया जाता है, तो v3, Accept-Language हेडर का इस्तेमाल करता है या डिफ़ॉल्ट रूप से en का इस्तेमाल करता है. वहीं, v4 डिफ़ॉल्ट रूप से जगह की स्थानीय भाषा और स्क्रिप्ट का इस्तेमाल करता है.
region regionCode नाम बदला गया. इस पैरामीटर को शामिल न करने पर, v3 की डिफ़ॉल्ट वैल्यू us होती है. हालांकि, v4 की कोई डिफ़ॉल्ट वैल्यू नहीं होती.
extra_computations हटा दिया गया इसकी जगह SearchDestinations तरीके का इस्तेमाल किया जाता है.

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

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 कॉम्पोनेंट फ़िल्टर फिर से बनाना

Geocoding v3 में फ़ॉरवर्ड जियोकोडिंग में components पैरामीटर शामिल था. इससे कुछ कॉम्पोनेंट (जैसे, components=country:US) के नतीजों को हार्ड फ़िल्टर किया जा सकता था. v4 में फ़ॉरवर्ड जियोकोडिंग, अनुरोध पैरामीटर में इस तरह के हार्ड फ़िल्टरिंग का समर्थन नहीं करता है. v4 में, पते की जानकारी को पाथ में बिना किसी स्ट्रक्चर वाली एक स्ट्रिंग के तौर पर या स्ट्रक्चर्ड क्वेरी पैरामीटर के तौर पर दिया जा सकता है. जैसे, address.addressLines, address.locality, address.administrativeArea, address.postalCode, और address.regionCode. स्ट्रक्चर्ड पैरामीटर, हार्ड फ़िल्टर के तौर पर काम नहीं करते. इसके बजाय, दिए गए सभी कॉम्पोनेंट को मिलाकर पूरा पता बनाया जाता है. एपीआई, इस पते को जियोकोड करने की कोशिश करेगा. एपीआई, सभी कॉम्पोनेंट में दिए गए पूरे पते के लिए सबसे सही मैच खोजता है. स्ट्रक्चर्ड तरीके से कॉम्पोनेंट उपलब्ध कराने से, एपीआई को मकसद को बेहतर तरीके से समझने में मदद मिल सकती है. खास तौर पर, जब पते की जानकारी अलग-अलग फ़ॉर्म फ़ील्ड से इकट्ठा की जाती है. इससे एपीआई को हर कॉम्पोनेंट में टाइपिंग की मामूली गलतियों या अस्पष्टताओं को मैनेज करने में मदद मिल सकती है. ऐसा इसलिए, क्योंकि हर फ़ील्ड में जानकारी का टाइप साफ़ तौर पर बताया गया है.

v3 के हार्ड कॉम्पोनेंट फ़िल्टर की तरह काम करने वाले फ़िल्टर बनाने के लिए, आपको v4 API से मिले results ऐरे पर क्लाइंट-साइड फ़िल्टरिंग लागू करनी होगी. यह फ़िल्टरिंग, जवाब में मौजूद postalAddress और addressComponents ऑब्जेक्ट के आधार पर की जाएगी.

नीचे दी गई टेबल में, v3 components फ़िल्टर और v4 postalAddress फ़ील्ड के बीच सबसे ज़्यादा मिलते-जुलते फ़िल्टर और फ़ील्ड दिखाए गए हैं:

v3 कॉम्पोनेंट फ़िल्टर v4 रिस्पॉन्स फ़ील्ड
country postalAddress.regionCode
postal_code postalAddress.postalCode
administrative_area postalAddress.administrativeArea या addressComponents

क्लाइंट-साइड फ़िल्टरिंग के उदाहरण

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

देश के हिसाब से फ़िल्टर करें

अपने अनुरोध में मौजूद address.regionCode को हर नतीजे में मौजूद postalAddress.regionCode से मैच करें. ध्यान दें कि एपीआई, अनुरोध में छोटे अक्षरों में लिखे गए देश/इलाके के कोड स्वीकार करता है. हालांकि, जवाब में वह हमेशा उन्हें बड़े अक्षरों में दिखाता है. इसलिए, तुलना करने से पहले आपको अपने इनपुट को बड़े अक्षरों में बदलना होगा.

Python कोड का उदाहरण 
def filter_by_country(results, region_code):
    return [
        res for res in results
        if res.get('postalAddress', {}).get('regionCode') == region_code.upper()
    ]

# Example usage:
# v4_response = ... # API call response
# filtered = filter_by_country(v4_response.get('results', []), 'US')
Node.js कोड का उदाहरण 
function filterByCountry(results, regionCode) {
    return results.filter(res => res.postalAddress?.regionCode === regionCode.toUpperCase());
}

// Example usage:
// const v4Response = ... # API call response
// const filtered = filterByCountry(v4Response.results, 'US');
राज्य के हिसाब से फ़िल्टर करना

अपनी क्वेरी के address.administrativeArea को हर नतीजे में मौजूद postalAddress.administrativeArea से मैच करें. देश के कोड की तरह ही, तुलना करने से पहले आपको अपने इनपुट को अपरकेस में नॉर्मलाइज़ करना चाहिए. यह सिर्फ़ तब भरोसेमंद होता है, जब आपके अनुरोध में administrativeArea को दो अक्षरों वाले स्टैंडर्ड शॉर्ट फ़ॉर्म के साथ दिया गया हो. जवाब में मौजूद postalAddress.administrativeArea, कई वजहों से ISO 3166-2 कोड के सफ़िक्स से सीधे तौर पर मैच नहीं हो सकता. सबसे पहले, कुछ इलाकों में ISO 3166-2 कोड से जुड़ा सबडिवीज़न, डाक पतों के स्टैंडर्ड रिप्रज़ेंटेशन का हिस्सा नहीं होता. उदाहरण के लिए, स्पेन में, addressComponents में एडमिनिस्ट्रेटिव एरिया लेवल 1 (जैसे, कैनरियास के लिए "CN") मौजूद हो सकता है. हालांकि, postalAddress.administrativeArea में लेवल 2 एरिया (जैसे, "सांता क्रूज़ डे टेनरीफ़") मौजूद हो सकता है. दूसरी बात, कुछ इलाकों में सबडिवीजन के नाम के छोटे रूप का इस्तेमाल आम तौर पर नहीं किया जाता. इसे postalAddress.administrativeArea में लंबे नाम के साथ दिखाया जाता है. इसी तरह की वजहों से, सबडिवीजन से जुड़े पते के कॉम्पोनेंट के लिए addressComponents.shortText, सबडिवीजन के ISO 3166-2 कोड के सफ़िक्स से मेल नहीं खा सकता. इसके अलावा, कुछ मामलों में सबडिविज़न को administrative_area_level_n के लिए पते के कॉम्पोनेंट के तौर पर दिखाया जा सकता है. यहां n की वैल्यू 1 से ज़्यादा होती है. सबसे सटीक नतीजे पाने के लिए, आपको postalAddress.administrativeArea और administrative_area_level_n टाइप (जैसे, administrative_area_level_1) वाले किसी भी addressComponents, दोनों में मैच देखना चाहिए.

Python कोड का उदाहरण 
def filter_by_admin_area(results, admin_area):
    target = admin_area.upper()
    filtered = []
    for res in results:
        # Check postalAddress
        pa_aa = res.get('postalAddress', {}).get('administrativeArea', '')
        if pa_aa == target:
            filtered.append(res)
            continue
        # Check all administrative area levels in addressComponents
        for comp in res.get('addressComponents', []):
            is_admin_level = any(t.startswith('administrative_area_level_')
                               for t in comp.get('types', []))
            if is_admin_level:
                short = comp.get('shortText', '')
                if short == target:
                    filtered.append(res)
                    break
    return filtered

# Example usage:
# filtered = filter_by_admin_area(v4_response.get('results', []), 'CA')
Node.js कोड का उदाहरण 
function filterByAdminArea(results, adminArea) {
    const target = adminArea.toUpperCase();
    return results.filter(res => {
        // Check postalAddress.administrativeArea
        if (res.postalAddress?.administrativeArea === target) {
            return true;
        }
        // Check addressComponents for any administrative area level
        return res.addressComponents?.some(c => {
            const isAdmin = c.types?.some(t => t.startsWith('administrative_area_level_'));
            return isAdmin && c.shortText === target;
        });
    });
}

// Example usage:
// const filtered = filterByAdminArea(v4Response.results, 'CA');
पिन कोड के हिसाब से फ़िल्टर करना

अपने अनुरोध में मौजूद address.postalCode को हर नतीजे में मौजूद postalAddress.postalCode से मैच करें. तुलना करने से पहले, आपको इनपुट और नतीजे, दोनों के पिन कोड को नॉर्मलाइज़ करना होगा. सामान्य बनाने का लॉजिक, देश/इलाके के हिसाब से तय होता है. एक बुनियादी तरीका यह है कि स्पेस और हाइफ़न हटा दिए जाएं और टेक्स्ट को एक ही केस में बदल दिया जाए.

पिन कोड के प्रीफ़िक्स (जैसे, यूनाइटेड किंगडम में "L2") या सफ़िक्स (जैसे, अमेरिका के पिन कोड में "+4") को मैनेज करने के लिए, ज़्यादा बेहतर नॉर्मलाइज़ेशन की ज़रूरत पड़ सकती है. नॉर्मलाइज़ेशन का लॉजिक, देश और पिन कोड के फ़ॉर्मैट के हिसाब से अलग-अलग होगा. आपको दिए गए नॉर्मलाइज़ेशन फ़ंक्शन में बदलाव करना पड़ सकता है या टारगेट किए जा रहे इलाकों के लिए, ज़्यादा बेहतर लॉजिक लागू करना पड़ सकता है.

यहां दिए गए उदाहरण में, अमेरिका के पिन कोड को हैंडल किया गया है. साथ ही, पांच अंकों के बेस पर मैच करने की अनुमति दी गई है. भले ही, ZIP+4 दिया गया हो या दिखाया गया हो.

Python कोड का उदाहरण (अमेरिका के पिन कोड पर आधारित) 
import re

def normalize_postal_code_us(pc):
    # Basic normalization for US: uppercase, alphanumeric only
    if not pc:
        return ""
    normalized = re.sub(r'[^A-Z0-9]', '', pc.upper())
    # Return only the first 5 digits for US ZIP codes
    return normalized[:5]

def filter_by_postal_code_us(results, postal_code):
    normalized_input = normalize_postal_code_us(postal_code)
    if not normalized_input:
        return []
    filtered_results = []
    for res in results:
        pa_pc = res.get('postalAddress', {}).get('postalCode', '')
        if normalize_postal_code_us(pa_pc) == normalized_input:
            filtered_results.append(res)
    return filtered_results

# Example usage:
# Matches '94043', '94043-1351', '940431351'
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043')
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043-1234')
Node.js कोड का उदाहरण (अमेरिका के पिन कोड पर आधारित) 
function normalizePostalCodeUs(pc) {
    // Basic normalization for US: uppercase, alphanumeric only
    const normalized = (pc || '').toUpperCase().replace(/[^A-Z0-9]/g, '');
    // Return only the first 5 digits for US ZIP codes
    return normalized.substring(0, 5);
}

function filterByPostalCodeUs(results, postalCode) {
    const normalizedInput = normalizePostalCodeUs(postalCode);
    if (!normalizedInput) {
        return [];
    }
    return results.filter(res => {
        const paPc = res.postalAddress?.postalCode || '';
        return normalizePostalCodeUs(paPc) === normalizedInput;
    });
}

// Example usage:
// Matches '94043', '94043-1351', '940431351'
// const filtered = filterByPostalCodeUs(v4Response.results, '94043');
// const filtered = filterByPostalCodeUs(v4Response.results, '94043-1234');

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

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

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

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

v3 पैरामीटर v4 पैरामीटर नोट
language languageCode नाम बदला गया. अगर इसे शामिल नहीं किया जाता है, तो v3, Accept-Language हेडर का इस्तेमाल करता है या डिफ़ॉल्ट रूप से en का इस्तेमाल करता है. वहीं, v4 डिफ़ॉल्ट रूप से जगह की स्थानीय भाषा और स्क्रिप्ट का इस्तेमाल करता है.
region regionCode नाम बदला गया. इस पैरामीटर को शामिल न करने पर, v3 की डिफ़ॉल्ट वैल्यू us होती है. हालांकि, v4 की कोई डिफ़ॉल्ट वैल्यू नहीं होती.
result_type types नाम बदला गया; बार-बार इस्तेमाल होने वाले क्वेरी पैरामीटर का इस्तेमाल करता है.
location_type granularity इसका नाम बदल दिया गया है. यह बार-बार इस्तेमाल किए गए क्वेरी पैरामीटर का इस्तेमाल करता है.
extra_computations हटा दिया गया इसकी जगह SearchDestinations तरीके का इस्तेमाल किया जाता है.

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

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 Address descriptors से माइग्रेट करना

अगर आपको Geocoding v3 की मदद से किसी जगह के बारे में ज़्यादा जानकारी पाने के लिए address_descriptor का इस्तेमाल करना है, तो आपको SearchDestinationsResponse के landmarks फ़ील्ड का इस्तेमाल करना होगा.

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

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

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

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

v3 पैरामीटर v4 पैरामीटर नोट
place_id अनुरोध के प्रोटो में place फ़ील्ड जगह का आईडी अब पाथ पैरामीटर places/{place} के तौर पर दिया जाता है. उदाहरण के लिए: https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. यह, अनुरोध में मौजूद जगह के फ़ील्ड से मैप होता है.
language languageCode नाम बदला गया. अगर v3 में भाषा की जानकारी नहीं दी जाती है, तो यह Accept-Language हेडर का इस्तेमाल करता है या डिफ़ॉल्ट रूप से en पर सेट हो जाता है. वहीं, v4 डिफ़ॉल्ट रूप से जगह की स्थानीय भाषा और स्क्रिप्ट पर सेट हो जाता है.
region regionCode नाम बदला गया. अगर इसे शामिल नहीं किया जाता है, तो v3 की वैल्यू डिफ़ॉल्ट रूप से us पर सेट हो जाती है. वहीं, v4 की कोई डिफ़ॉल्ट वैल्यू नहीं होती.

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

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 - यह एक नया वैकल्पिक फ़ील्ड है. इसमें नेविगेशन पॉइंट के लिए, किसी व्यक्ति के लिए आसानी से पढ़ा जा सकने वाला नाम होगा. उदाहरण के लिए, "5th Ave".
  • location - यह LatLng टाइप की जगह है. यह Geocoding API v3 में इस्तेमाल किए गए फ़ॉर्मैट से अलग है.
  • travelModes - यह Geocoding API v3 के नेविगेशन पॉइंट के restrictedTravelModes फ़ील्ड जैसा ही है. इनम की संभावित वैल्यू एक जैसी होती हैं. इनमें सिर्फ़ यह अंतर होता है कि यह फ़ील्ड अब नेविगेशन पॉइंट के लिए, यात्रा के उन मोड को दिखाता है जिन्हें इस्तेमाल किया जा सकता है. इसमें यात्रा के उन मोड को नहीं दिखाया जाता जिन पर पाबंदी लगी है.
  • usage - यह एक नया फ़ील्ड है. इसमें नेविगेशन पॉइंट के साथ काम करने वाले इस्तेमाल के उदाहरण शामिल होते हैं.

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

किसी 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 में बिल्डिंग की आउटलाइन के फ़ॉर्मैट से मेल खाता है. यह GeoJSON फ़ॉर्मैट है, जिसमें आरएफ़सी 7946 फ़ॉर्मैट का इस्तेमाल किया जाता है.

मैदान

आउटलाइन बनाने की तरह ही, 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 में ग्राउंड की आउटलाइन के फ़ॉर्मैट से मेल खाता है. यह GeoJSON फ़ॉर्मैट है, जो आरएफ़सी 7946 फ़ॉर्मैट का इस्तेमाल करता है.

नतीजे कितने सटीक हैं

Geocoding API v3 में, रिस्पॉन्स ज्यामिति में मौजूद location_type फ़ील्ड से नतीजों की सटीक जानकारी मिलती थी. साथ ही, कुछ क्लाइंट इन वैल्यू (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER, और APPROXIMATE) के आधार पर नतीजों को रैंक या फ़िल्टर करते थे. Geocoding API v4 के स्टैंडर्ड माइग्रेशन में, इस फ़ील्ड का नाम बदलकर granularity कर दिया गया है.

Destinations API (v4 SearchDestinations) में, location_type फ़ील्ड मौजूद नहीं है. इसके बजाय, स्पेशल ऑडियो की जानकारी को अलग तरीके से मैनेज किया जाता है:

  • क्लाइंट-साइड पर मैन्युअल तरीके से फ़िल्टर करने की ज़रूरत नहीं है: स्टैंडर्ड जियोकोडिंग, अलग-अलग बारीकियों के हिसाब से कई नतीजे देती है. हालांकि, SearchDestinations तरीका, जब भी संभव हो, एक ऑप्टिमाइज़ की गई डेस्टिनेशन पर ले जाकर, भ्रम को कम करता है. इससे क्लाइंट को यह तय करने के लिए, जगह के हिसाब से फ़िल्टर करने की ज़रूरत नहीं पड़ती कि कौनसा नतीजा सबसे अच्छा है.
  • स्ट्रक्चर टाइप और डिसप्ले पॉलीगॉन से दिखाई गई जगह की जानकारी: जगह की ज्यामिति और स्ट्रक्चर को इनसे दिखाया जाता है:
    • displayPolygon (सटीक ज्यामिति के लिए).
    • placeView ऑब्जेक्ट में मौजूद structureType फ़ील्ड.
  • स्ट्रक्चर टाइप की मैपिंग:
    • POINT, BUILDING या SECTION का structureType, आम तौर पर वही होता है जिसे पहले ROOFTOP कहा जाता था.
    • GROUNDS का structureType आम तौर पर GEOMETRIC_CENTER के बराबर होता है.

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

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/v4/geocode/destinations

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

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

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

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

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

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