Maps JavaScript API लोड करना

इस गाइड में, Maps JavaScript API को लोड करने का तरीका बताया गया है. ऐसा करने के तीन तरीके हैं:

• डाइनैमिक लाइब्रेरी इंपोर्ट का इस्तेमाल करना
• डायरेक्ट स्क्रिप्ट लोडिंग टैग का इस्तेमाल करना
• NPM js-api-loader पैकेज का इस्तेमाल करना

डाइनैमिक लाइब्रेरी इंपोर्ट का इस्तेमाल करना

डाइनैमिक लाइब्रेरी इंपोर्ट की मदद से, लाइब्रेरी को रनटाइम पर लोड किया जा सकता है. इससे, आपको ज़रूरत के समय ही ज़रूरी लाइब्रेरी का अनुरोध करने की सुविधा मिलती है. इसके बजाय, लोड होने के समय सभी लाइब्रेरी का अनुरोध करने की सुविधा मिलती है. यह आपके पेज को Maps JavaScript API को कई बार लोड करने से भी बचाता है.

Maps JavaScript API को लोड करने के लिए, अपने ऐप्लिकेशन कोड में इनलाइन बूटस्ट्रैप लोडर जोड़ें. इसे नीचे दिए गए स्निपेट में दिखाया गया है:

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

बूटस्ट्रैप लोडर कोड को सीधे अपने JavaScript कोड में भी जोड़ा जा सकता है.

रनटाइम पर लाइब्रेरी लोड करने के लिए, await ऑपरेटर का इस्तेमाल करके async फ़ंक्शन में importLibrary() को कॉल करें. ज़रूरी क्लास के लिए वैरिएबल तय करने से, आपको क्वालिफ़ाइड पाथ (जैसे, google.maps.Map) का इस्तेमाल नहीं करना पड़ता. इसे कोड के इस उदाहरण में दिखाया गया है:

let map;
async function initMap() {
    const { Map } = (await google.maps.importLibrary('maps'));
    map = new Map(document.getElementById('map'), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}
initMap();
index.js

आपका फ़ंक्शन, ज़रूरी क्लास के लिए वैरिएबल का एलान किए बिना भी लाइब्रेरी लोड कर सकता है. यह तब खास तौर पर काम आता है, जब आपने gmp-map एलिमेंट का इस्तेमाल करके कोई मैप जोड़ा हो. वैरिएबल के बिना, आपको क्वालिफ़ाइड पाथ का इस्तेमाल करना होगा. उदाहरण के लिए google.maps.Map:

let map;
let center =  { lat: -34.397, lng: 150.644 };

async function initMap() {
  await google.maps.importLibrary("maps");
  await google.maps.importLibrary("marker");

  map = new google.maps.Map(document.getElementById("map"), {
    center,
    zoom: 8,
    mapId: "DEMO_MAP_ID",
  });

  addMarker();
}

async function addMarker() {
  const marker = new google.maps.marker.AdvancedMarkerElement({
    map,
    position: center,
  });
}

initMap();

इसके अलावा, यहां दिखाए गए तरीके से लाइब्रेरी को सीधे एचटीएमएल में लोड किया जा सकता है:

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

डाइनैमिक लाइब्रेरी लोडिंग एपीआई पर माइग्रेट करने का तरीका जानें.

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

• key: आपकी एपीआई कुंजी. जब तक कोई मान्य एपीआई पासकोड नहीं दिया जाता, तब तक Maps JavaScript API लोड नहीं होगा.

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

• v: Maps JavaScript API का वह वर्शन जिसे लोड करना है.

• libraries: Maps JavaScript API की अतिरिक्त लाइब्रेरी का एक कलेक्शन, जिसे प्रीलोड करना है. आम तौर पर, लाइब्रेरी का एक तय सेट तय करने का सुझाव नहीं दिया जाता. हालांकि, यह उन डेवलपर के लिए उपलब्ध है जो अपनी वेबसाइट पर कैश मेमोरी के इस्तेमाल के तरीके को बेहतर बनाना चाहते हैं. हालांकि, इस्तेमाल से पहले चुनी गई हर लाइब्रेरी के लिए google.maps.importLibrary() को कॉल करना ज़रूरी है.

• language: इस्तेमाल की जाने वाली भाषा. इससे कंट्रोल के नाम, कॉपीराइट की सूचनाएं, ड्राइविंग के दिशा-निर्देश, कंट्रोल के लेबल, और सेवा के अनुरोधों के जवाबों पर असर पड़ता है. इस्तेमाल की जा सकने वाली भाषाओं की सूची देखें.

• region: इस्तेमाल किया जाने वाला क्षेत्र कोड. इससे किसी देश या इलाके के हिसाब से, एपीआई के काम करने के तरीके में बदलाव होता है.

• authReferrerPolicy: Maps JS के ग्राहक, Cloud Console में एचटीटीपी रेफ़रर से जुड़ी पाबंदियां कॉन्फ़िगर कर सकते हैं. इससे यह तय किया जा सकता है कि किन यूआरएल को किसी खास एपीआई पासकोड का इस्तेमाल करने की अनुमति है. डिफ़ॉल्ट रूप से, इन पाबंदियों को इस तरह कॉन्फ़िगर किया जा सकता है कि सिर्फ़ कुछ पाथ को एपीआई पासकोड का इस्तेमाल करने की अनुमति मिले. अगर एक ही डोमेन या ऑरिजिन पर मौजूद किसी यूआरएल को एपीआई पासकोड का इस्तेमाल करना है, तो authReferrerPolicy: "origin" को सेट करके, Maps JavaScript API से अनुरोधों को अनुमति देते समय भेजे जाने वाले डेटा की मात्रा को सीमित किया जा सकता है. जब इस पैरामीटर को सेट किया जाता है और Cloud Console पर एचटीटीपी रेफ़रर से जुड़ी पाबंदियां चालू होती हैं, तब Maps JavaScript API सिर्फ़ तब लोड हो पाएगा, जब कोई ऐसी एचटीटीपी रेफ़रर से जुड़ी पाबंदी मौजूद हो जो पाथ के बिना, मौजूदा वेबसाइट के डोमेन से मेल खाती हो.

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

• channel: हर चैनल के हिसाब से इस्तेमाल को ट्रैक करना लेख पढ़ें.

• internalUsageAttributionIds: इस्तेमाल किए गए एट्रिब्यूशन आईडी का एक कलेक्शन. इससे Google को यह समझने में मदद मिलती है कि डेवलपर के लिए कौनसी लाइब्रेरी और सैंपल मददगार हैं. जैसे, मार्कर क्लस्टरिंग लाइब्रेरी का इस्तेमाल. इस्तेमाल की जानकारी देने वाला एट्रिब्यूशन आईडी न भेजने के लिए, इस प्रॉपर्टी को मिटाना या वैल्यू को खाली कलेक्शन ([]) पर सेट करना सुरक्षित है. सिर्फ़ यूनीक वैल्यू भेजी जाएंगी. ज़्यादा जानकारी के लिए, Google Maps Platform के समाधानों का पैरामीटर देखें.

ध्यान दें: solutionChannel पैरामीटर अब भी मान्य है, लेकिन इसका इस्तेमाल करने का सुझाव नहीं दिया जाता. इसके बजाय, internalUsageAttributionIds का इस्तेमाल करें.

डायरेक्ट स्क्रिप्ट लोडिंग टैग का इस्तेमाल करना

इस सेक्शन में, डायरेक्ट स्क्रिप्ट लोडिंग टैग इस्तेमाल करने का तरीका बताया गया है. डाइरेक्ट स्क्रिप्ट, मैप लोड होने पर लाइब्रेरी लोड करती है. इसलिए, यह gmp-map एलिमेंट का इस्तेमाल करके बनाए गए मैप को आसान बना सकती है. ऐसा इसलिए, क्योंकि इससे रनटाइम में लाइब्रेरी का अनुरोध करने की ज़रूरत नहीं पड़ती. डायरेक्ट स्क्रिप्ट लोडिंग टैग, स्क्रिप्ट लोड होने पर अनुरोध की गई सभी लाइब्रेरी को एक साथ लोड करता है. इसलिए, कुछ ऐप्लिकेशन की परफ़ॉर्मेंस पर असर पड़ सकता है. पेज लोड होने पर, डायरेक्ट स्क्रिप्ट लोडिंग टैग को सिर्फ़ एक बार शामिल करें.

ध्यान दें: डायरेक्ट स्क्रिप्ट लोडिंग टैग के लोड होने के बाद ही, importLibrary को कॉल किया जा सकता है.

स्क्रिप्ट टैग जोड़ना

Maps JavaScript API को एचटीएमएल फ़ाइल में इनलाइन लोड करने के लिए, यहां दिखाए गए तरीके से script टैग जोड़ें.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

स्क्रिप्ट को सीधे तौर पर लोड करने के लिए यूआरएल पैरामीटर

इस सेक्शन में, उन सभी पैरामीटर के बारे में बताया गया है जिन्हें Maps JavaScript API लोड करते समय, स्क्रिप्ट लोड करने वाले यूआरएल की क्वेरी स्ट्रिंग में तय किया जा सकता है. कुछ पैरामीटर ज़रूरी होते हैं, जबकि कुछ ज़रूरी नहीं होते हैं. यूआरएल में स्टैंडर्ड के तौर पर, सभी पैरामीटर को एंपरसैंड (&) वर्ण का इस्तेमाल करके अलग किया जाता है.

यहां दिए गए उदाहरण यूआरएल में, सभी संभावित पैरामीटर के लिए प्लेसहोल्डर मौजूद हैं:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

यहां दिए गए उदाहरण में, script टैग में मौजूद यूआरएल, Maps JavaScript API को लोड करता है:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

ज़रूरी पैरामीटर (डायरेक्ट) {:.hide-from-toc}

Maps JavaScript API लोड करते समय, इन पैरामीटर की ज़रूरत होती है.

• key: आपकी एपीआई कुंजी. जब तक कोई मान्य एपीआई पासकोड नहीं दिया जाता, तब तक Maps JavaScript API लोड नहीं होगा.

ज़रूरी नहीं पैरामीटर (डायरेक्ट) {:.hide-from-toc}

इन पैरामीटर का इस्तेमाल करके, Maps JavaScript API के किसी खास वर्शन का अनुरोध करें, अतिरिक्त लाइब्रेरी लोड करें, अपने मैप को स्थानीय भाषा में दिखाएं या एचटीटीपी रेफ़रर की जांच करने की नीति तय करें

• loading: यह कोड लोड करने की ऐसी रणनीति है जिसका इस्तेमाल Maps JavaScript API कर सकता है. async पर सेट करें, ताकि यह पता चल सके कि Maps JavaScript API को सिंक्रोनस तरीके से लोड नहीं किया गया है. साथ ही, स्क्रिप्ट के load इवेंट से कोई JavaScript कोड ट्रिगर नहीं होता है. हमारा सुझाव है कि बेहतर परफ़ॉर्मेंस के लिए, इसे async पर सेट करें. (Maps JavaScript API उपलब्ध होने पर कार्रवाइयां करने के लिए, callback पैरामीटर का इस्तेमाल करें.) यह सुविधा, 3.55 वर्शन से उपलब्ध है.

• callback: यह एक ग्लोबल फ़ंक्शन का नाम है. Maps JavaScript API पूरी तरह से लोड होने के बाद, इसे कॉल किया जाता है.

• v: Maps JavaScript API का वह वर्शन जिसका इस्तेमाल करना है.

• libraries: कॉमा लगाकर अलग की गई, Maps JavaScript API की उन लाइब्रेरी की सूची जिन्हें लोड करना है.

• language: इस्तेमाल की जाने वाली भाषा. इससे कंट्रोल के नाम, कॉपीराइट की सूचनाएं, ड्राइविंग के निर्देश, और कंट्रोल के लेबल के साथ-साथ सेवा के अनुरोधों के जवाबों पर असर पड़ता है. इस्तेमाल की जा सकने वाली भाषाओं की सूची देखें.

• region: इस्तेमाल किया जाने वाला क्षेत्र कोड. इससे किसी देश या इलाके के हिसाब से, एपीआई के काम करने के तरीके में बदलाव होता है.

• auth_referrer_policy: ग्राहक, Cloud Console में जाकर एचटीटीपी रेफ़रर से जुड़ी पाबंदियां कॉन्फ़िगर कर सकते हैं. इससे यह तय किया जा सकता है कि किन यूआरएल को किसी खास एपीआई कुंजी का इस्तेमाल करने की अनुमति है. डिफ़ॉल्ट रूप से, इन पाबंदियों को कॉन्फ़िगर किया जा सकता है, ताकि सिर्फ़ कुछ पाथ को एपीआई पासकोड का इस्तेमाल करने की अनुमति दी जा सके. अगर एक ही डोमेन या ऑरिजिन पर मौजूद किसी भी यूआरएल को एपीआई पासकोड का इस्तेमाल करना है, तो auth_referrer_policy=origin को सेट करके, Maps JavaScript API से अनुरोधों को अनुमति देते समय भेजे जाने वाले डेटा की मात्रा को सीमित किया जा सकता है. यह सुविधा, 3.46 और उसके बाद के वर्शन में उपलब्ध है. जब इस पैरामीटर को सेट किया जाता है और Cloud Console पर एचटीटीपी रेफ़रर से जुड़ी पाबंदियां चालू होती हैं, तब Maps JavaScript API सिर्फ़ तब लोड हो पाएगा, जब एचटीटीपी रेफ़रर से जुड़ी पाबंदी मौजूद हो. यह पाबंदी, मौजूदा वेबसाइट के डोमेन से मेल खाती हो और इसमें कोई पाथ न दिया गया हो.

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

• channel: हर चैनल के हिसाब से इस्तेमाल को ट्रैक करना लेख पढ़ें.

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

ध्यान दें: solution_channel पैरामीटर अब भी मान्य है, लेकिन इसका इस्तेमाल करने का सुझाव नहीं दिया जाता. इसके बजाय, internal_usage_attribution_ids का इस्तेमाल करें.

NPM js-api-loader पैकेज का इस्तेमाल करना

अहम जानकारी: v2.0.0 रिलीज़ में, कोड को फिर से लिखा गया है. इसमें पुरानी Loader क्लास को दो फ़ंक्शन वाले एपीआई से बदल दिया गया है. ये फ़ंक्शन setOptions() और importLibrary() हैं. इस बदलाव से, Maps API की अलग-अलग लाइब्रेरी को ज़रूरत के हिसाब से डाइनैमिक तरीके से लोड किया जा सकेगा. साथ ही, शुरुआती पेज की परफ़ॉर्मेंस को बेहतर बनाने के लिए, सुविधा से जुड़े डाउनलोड को बाद के लिए टाला जा सकेगा.

@googlemaps/js-api-loader पैकेज उपलब्ध है. इसे NPM पैकेज मैनेजर का इस्तेमाल करके लोड किया जा सकता है. इसे इंस्टॉल करने के लिए, यह कमांड डालें:

npm install @googlemaps/js-api-loader

पैकेज को यहां दिखाए गए तरीके से इंपोर्ट करें:

import { setOptions, importLibrary } from "@googlemaps/js-api-loader"

लोडर, लाइब्रेरी उपलब्ध कराने के लिए प्रॉमिस का इस्तेमाल करता है. importLibrary() तरीके का इस्तेमाल करके लाइब्रेरी लोड करें. यहां दिए गए उदाहरण में, मैप को लोड करने के लिए लोडर का इस्तेमाल करने का तरीका दिखाया गया है:

TypeScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

async function initMap(): Promise<void> {
    // Set loader options.
    setOptions({
        key: API_KEY,
        v: 'weekly',
    });

    // Load the Maps library.
    const { Map } = (await importLibrary('maps')) as google.maps.MapsLibrary;

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    const map = new Map(
        document.getElementById('map') as HTMLElement,
        mapOptions
    );
}

initMap();
index.ts

ध्यान दें: TypeScript और Google Maps का इस्तेमाल करने के बारे में गाइड पढ़ें.

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';
async function initMap() {
    // Set loader options.
    setOptions({
        key: API_KEY,
        v: 'weekly',
    });
    // Load the Maps library.
    const { Map } = (await importLibrary('maps'));
    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };
    // Declare the map.
    const map = new Map(document.getElementById('map'), mapOptions);
}
initMap();
index.js

पूरा उदाहरण कोड देखें.

Dynamic Library Import API पर माइग्रेट करना

इस सेक्शन में, Dynamic Library Import API का इस्तेमाल करने के लिए, इंटिग्रेशन को माइग्रेट करने का तरीका बताया गया है.

माइग्रेशन के चरण

सबसे पहले, डायरेक्ट स्क्रिप्ट लोडिंग टैग को इनलाइन बूटस्ट्रैप लोडर टैग से बदलें.

पहले

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&callback=initMap">
</script>

बाद में

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

इसके बाद, अपने ऐप्लिकेशन कोड को अपडेट करें:

• अपने initMap() फ़ंक्शन को एसिंक्रोनस में बदलें.
• अपनी ज़रूरत की लाइब्रेरी को लोड करने और उन्हें ऐक्सेस करने के लिए, importLibrary() को कॉल करें.

पहले

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

बाद में

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();