खास जानकारी

प्लैटफ़ॉर्म चुनें: Android iOS JavaScript

Maps JavaScript API की मदद से, वेब पेजों और मोबाइल डिवाइसों पर दिखाने के लिए, अपने कॉन्टेंट और इमेज के साथ मैप को पसंद के मुताबिक बनाया जा सकता है. Maps JavaScript API में चार बुनियादी तरह के मैप (रोडमैप, सैटलाइट, हाइब्रिड, और इलाका) की सुविधा है. लेयर और स्टाइल, कंट्रोल और इवेंट, कई सेवाओं और लाइब्रेरी का इस्तेमाल करके इनमें बदलाव किया जा सकता है.

दर्शक

यह दस्तावेज़ उन लोगों के लिए बनाया गया है जिन्हें JavaScript प्रोग्रामिंग और ऑब्जेक्ट-ओरिएंटेड प्रोग्रामिंग के सिद्धांतों के बारे में जानकारी है. उपयोगकर्ताओं के नज़रिये से आपको मैप के बारे में भी जानकारी होनी चाहिए. वेब पर JavaScript के कई ट्यूटोरियल उपलब्ध हैं.

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

नमस्ते, दुनिया

एक आसान उदाहरण देखकर, Maps JavaScript API के बारे में आसानी से सीखा जा सकता है. नीचे दिए गए उदाहरण में उस मैप को दिखाया गया है जो सिडनी, न्यू साउथ वेल्स, ऑस्ट्रेलिया पर आधारित है.

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.ts

JavaScript

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

सीएसएस

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

style.css

एचटीएमएल

<html>
  <head>
    <title>Simple Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- prettier-ignore -->
    <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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html
उदाहरण देखें

सैंपल आज़माएं

इस आसान उदाहरण में भी, ध्यान देने के लिए कुछ चीज़ें हैं:

  1. हम <!DOCTYPE html> का इस्तेमाल करके, ऐप्लिकेशन को HTML5 के तौर पर एलान करते हैं.
  2. मैप को होल्ड करने के लिए, हम "मैप" नाम का div एलिमेंट बनाते हैं.
  3. हम एक JavaScript फ़ंक्शन के बारे में बताते हैं, जो div में मैप बनाता है.
  4. हम बूटस्ट्रैप लोडर का इस्तेमाल करके Maps JavaScript API को लोड करते हैं.

इन चरणों से जुड़ी ज़्यादा जानकारी नीचे दी गई है.

Maps JavaScript API लोड करना

बूटस्ट्रैप लोडर Maps JavaScript API को लोड करने का सुझाया गया तरीका है. विकल्प के तौर पर, JS API लोडर भी उपलब्ध कराया गया है. हमारा सुझाव है कि आप दोनों तरीकों की समीक्षा करें. साथ ही, ऐसा तरीका चुनें जो आपके प्रोजेक्ट में कोड के स्ट्रक्चर के हिसाब से सबसे सही हो.

ज़्यादा जानकारी के लिए, 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>

रनटाइम पर लाइब्रेरी लोड करने के लिए, await ऑपरेटर का इस्तेमाल करें, ताकि किसी एसिंक फ़ंक्शन से importLibrary() को कॉल किया जा सके, जैसा कि यहां दिखाया गया है:

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.ts

JavaScript

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

एनपीएम जेएस-एपीआई-लोडर पैकेज

NPM का इस्तेमाल करके, Maps JavaScript API को लोड करने के लिए, @googlemaps/js-api-loader का इस्तेमाल करें. नीचे दिए गए निर्देश का इस्तेमाल करके, NPM की मदद से इसे इंस्टॉल करें:

npm install @googlemaps/js-api-loader

यह पैकेज ऐप्लिकेशन में इसके साथ आयात किया जा सकता है:

import { Loader } from "@googlemaps/js-api-loader"

लोडर, प्रॉमिस और कॉलबैक इंटरफ़ेस दिखाता है. यहां दिए गए उदाहरण में, प्रॉमिस के डिफ़ॉल्ट तरीके load() के इस्तेमाल के बारे में बताया गया है.

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

index.js

अपने ऐप्लिकेशन को HTML5 के रूप में घोषित करें

हमारा सुझाव है कि आप अपने वेब ऐप्लिकेशन में सही DOCTYPE का एलान करें. यहां दिए गए उदाहरणों में, हमने आसान HTML5 DOCTYPE का इस्तेमाल करके, अपने ऐप्लिकेशन को HTML5 के तौर पर एलान किया है, जैसा कि नीचे दिखाया गया है:

<!DOCTYPE html>

ज़्यादातर मौजूदा ब्राउज़र इस DOCTYPE के साथ बताए गए कॉन्टेंट को "स्टैंडर्ड मोड" में रेंडर करेंगे. इसका मतलब है कि आपका ऐप्लिकेशन, क्रॉस-ब्राउज़र के हिसाब से ज़्यादा काम का होना चाहिए. DOCTYPE को ग्रेसफ़ुल तरीके से डिग्रेड करने के लिए भी डिज़ाइन किया गया है. जिन ब्राउज़र को यह समझ नहीं आता कि वे इसे अनदेखा कर देंगे और उनका कॉन्टेंट दिखाने के लिए "क्वर्क्स मोड" का इस्तेमाल करेंगे.

ध्यान दें कि क्वर्क मोड (पुराने वर्शन पर काम करने की सुविधा) के अंदर काम करने वाले कुछ सीएसएस, स्टैंडर्ड मोड में मान्य नहीं हैं. खास तौर पर, प्रतिशत पर आधारित सभी साइज़, पैरंट ब्लॉक एलिमेंट से इनहेरिट होने चाहिए. अगर उनमें से कोई भी ऐवरेज कोई साइज़ तय नहीं कर पाता है, तो उसे 0 x 0 पिक्सल माना जाता है. इसी वजह से, हम यह <style> एलान शामिल करते हैं:

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

सीएसएस के इस एलान से पता चलता है कि मैप कंटेनर <div> (आईडी map वाला) को, एचटीएमएल बॉडी की 100% ऊंचाई का इस्तेमाल करना चाहिए. ध्यान दें कि हमें खास तौर पर <body> और <html> के लिए भी इन प्रतिशत की जानकारी देनी होगी.

Maps JavaScript API लोड हो रहा है

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

इनलाइन लोडिंग

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

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

डाइनैमिक लोडिंग

एक अलग JavaScript फ़ाइल का इस्तेमाल करके, Maps JavaScript API को डाइनैमिक तौर पर लोड करने के लिए, नीचे दिया गया उदाहरण देखें. इस तरीके से, आपको एपीआई के साथ काम करने के लिए, अपने सभी कोड को एक अलग .js फ़ाइल से मैनेज करने की सुविधा मिलती है. यह तरीका, स्क्रिप्ट टैग को इनलाइन जोड़ने के जैसा ही है.

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);

डाइनैमिक लोडिंग

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

npm install @googlemaps/js-api-loader

यह पैकेज ऐप्लिकेशन में इसके साथ आयात किया जा सकता है:

import { Loader } from "@googlemaps/js-api-loader"

लोडर, प्रॉमिस और कॉलबैक इंटरफ़ेस दिखाता है. यहां दिए गए उदाहरण में, प्रॉमिस के डिफ़ॉल्ट तरीके load() के इस्तेमाल के बारे में बताया गया है.

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

index.js

स्क्रिप्ट टैग एट्रिब्यूट

ऊपर दिए गए उदाहरणों में ध्यान दें कि script टैग पर कई एट्रिब्यूट सेट किए गए हैं. हालांकि, हमारा सुझाव है कि आप ये एट्रिब्यूट इस्तेमाल करें. यहां हर एट्रिब्यूट के बारे में जानकारी दी गई है.

  • src: वह यूआरएल जहां से Maps JavaScript API लोड किया जाता है. इसमें वे सभी सिंबल और परिभाषाएं शामिल होती हैं जिनकी ज़रूरत आपको Maps JavaScript API का इस्तेमाल करने के लिए होती है. इस उदाहरण में दिए गए यूआरएल में दो पैरामीटर हैं: key, जहां एपीआई पासकोड उपलब्ध कराया जाता है. callback, जहां Maps JavaScript API के पूरी तरह लोड होने पर कॉल किए जाने वाले ग्लोबल फ़ंक्शन का नाम बताया जाता है. यूआरएल पैरामीटर के बारे में ज़्यादा पढ़ें.
  • async: यह ब्राउज़र को एसिंक्रोनस रूप से स्क्रिप्ट डाउनलोड करने और उसे लागू करने के लिए कहता है. स्क्रिप्ट चलाने पर, यह callback पैरामीटर का इस्तेमाल करके बताए गए फ़ंक्शन को कॉल करेगी.

लाइब्रेरी

यूआरएल के ज़रिए Maps JavaScript API को लोड करते समय, अतिरिक्त लाइब्रेरी लोड की जा सकती है. इसके लिए, एसिंक्रोनस फ़ंक्शन में importLibrary() को कॉल करने के लिए, await ऑपरेटर का इस्तेमाल किया जा सकता है. हालांकि, ऐसा करना ज़रूरी नहीं है. लाइब्रेरी, कोड के मॉड्यूल होते हैं. ये मुख्य Maps JavaScript API को ज़्यादा सुविधाएं देते हैं. हालांकि, इन्हें तब तक लोड नहीं किया जाता, जब तक कि आप खास तौर से इसके लिए अनुरोध न करें. ज़्यादा जानकारी के लिए, Maps JavaScript API में लाइब्रेरी देखें.

मैप के डीओएम एलिमेंट

<div id="map"></div>

किसी वेब पेज पर मैप दिखे, इसके लिए हमें एक जगह बुक करनी होगी. आम तौर पर, हम नाम वाला div एलिमेंट बनाते हैं और ब्राउज़र के दस्तावेज़ ऑब्जेक्ट मॉडल (डीओएम) में इस एलिमेंट का रेफ़रंस हासिल करते हैं.

ऊपर दिए गए उदाहरण में, हमने मैप div की ऊंचाई को "100%" पर सेट करने के लिए सीएसएस का इस्तेमाल किया. यह बड़ा होकर मोबाइल डिवाइसों पर साइज़ में फ़िट हो जाएगा. ब्राउज़र की स्क्रीन के साइज़ और पैडिंग के हिसाब से, आपको चौड़ाई और ऊंचाई की वैल्यू में बदलाव करना पड़ सकता है. ध्यान दें कि div आम तौर पर उनके मौजूदा एलिमेंट से अपनी चौड़ाई लेते हैं और खाली div की ऊंचाई आम तौर पर 0 होती है. इस वजह से, आपको <div> पर हमेशा साफ़ तौर पर ऊंचाई सेट करनी होगी.

मैप विकल्प

हर मैप के लिए दो ज़रूरी विकल्प होते हैं: center और zoom.

map = new Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

ज़ूम स्तर

मैप को जिस शुरुआती रिज़ॉल्यूशन पर दिखाना है वह zoom प्रॉपर्टी से सेट किया जाता है. यहां ज़ूम 0, Earth के मैप को पूरी तरह से ज़ूम आउट कर देता है और बड़े ज़ूम लेवल, ज़्यादा रिज़ॉल्यूशन पर ज़ूम इन करते हैं.

zoom: 8

पूरे पृथ्वी का एक ही इमेज के रूप में एक मैप देने के लिए या तो बहुत बड़े मैप की ज़रूरत होती है या बहुत कम रिज़ॉल्यूशन वाले छोटे मैप की ज़रूरत होती है. इस वजह से, Google Maps और Maps JavaScript API में मौजूद मैप इमेज को मैप "टाइल" और "ज़ूम लेवल" में बांट दिया जाता है. कम ज़ूम लेवल पर, मैप की टाइल का एक छोटा सेट बड़े हिस्से को कवर कर लेता है. ज़्यादा ज़ूम लेवल पर, टाइल का रिज़ॉल्यूशन ज़्यादा होता है और वे छोटे साइज़ की होती हैं. इस सूची में जानकारी का वह अनुमानित लेवल दिखाया गया है जिसे हर ज़ूम लेवल पर देखा जा सकता है:

  • 1: दुनिया
  • 5: लैंडमास/महाद्वीप
  • 10: शहर
  • 15: सड़कें
  • 20: इमारतें

यहां दी गई तीन इमेज में 0, 7, और 18 के ज़ूम लेवल पर टोक्यो की एक ही जगह दिखाई गई है.

इस बारे में जानकारी के लिए कि Maps JavaScript API, ज़ूम के मौजूदा लेवल के आधार पर टाइल कैसे लोड करता है, मैप और टाइल कोऑर्डिनेट करने की गाइड देखें.

मैप के ऑब्जेक्ट

map = new Map(document.getElementById("map"), {...});

किसी मैप को दिखाने वाली JavaScript क्लास, Map क्लास होती है. इस क्लास के ऑब्जेक्ट, किसी पेज पर एक मैप तय करते हैं. (इस क्लास के एक से ज़्यादा इंस्टेंस बनाए जा सकते हैं — हर ऑब्जेक्ट, पेज पर एक अलग मैप तय करेगा.) हम JavaScript new ऑपरेटर का इस्तेमाल करके, इस क्लास का एक नया इंस्टेंस बनाते हैं.

नया मैप इंस्टेंस बनाते समय, पेज में <div> एचटीएमएल एलिमेंट को मैप के कंटेनर के तौर पर चुना जाता है. एचटीएमएल नोड, JavaScript document ऑब्जेक्ट से जुड़े होते हैं. हमें इस एलिमेंट का रेफ़रंस, document.getElementById() तरीके से मिलता है.

यह कोड एक वैरिएबल (जिसका नाम map है) के बारे में बताता है और उस वैरिएबल को एक नए Map ऑब्जेक्ट को असाइन करता है. Map() फ़ंक्शन को कंस्ट्रक्टर के तौर पर जाना जाता है और इसकी परिभाषा यहां दी गई है:

निर्माता जानकारी
Map(mapDiv:Node, opts?:MapOptions ) दिए गए एचटीएमएल कंटेनर के अंदर एक नया मैप बनाता है — जो आम तौर पर एक DIV एलिमेंट होता है — पास दिए गए किसी भी (ज़रूरी नहीं) पैरामीटर का इस्तेमाल करके किया जाता है.

समस्या हल करना

एपीआई पासकोड और बिलिंग से जुड़ी गड़बड़ियां

कुछ मामलों में, गहरे रंग वाला मैप या 'नेगेटिव' Street View, "सिर्फ़ डेवलपमेंट के लिए" टेक्स्ट वॉटरमार्क के साथ दिख सकता है. इस व्यवहार से आम तौर पर, एपीआई पासकोड या बिलिंग से जुड़ी समस्याओं की जानकारी मिलती है. Google Maps Platform के प्रॉडक्ट इस्तेमाल करने के लिए, आपके खाते पर बिलिंग की सुविधा चालू होनी चाहिए. साथ ही, सभी अनुरोधों में मान्य एपीआई पासकोड शामिल होना चाहिए. यहां दिए गए फ़्लो से, इस समस्या को हल करने में मदद मिलेगी:

अगर आपका कोड काम नहीं कर रहा है, तो:

आपके मैप कोड को सही तरीके से चलाने में मदद करने के लिए, ब्रेंडन केनी और मनो मार्क्स ने इस वीडियो में कुछ आम गलतियों के बारे में बताया है और उन्हें ठीक करने का तरीका भी बताया है.

  • टाइपिंग की गलतियां ढूंढें. याद रखें कि JavaScript एक केस-सेंसिटिव (बड़े और छोटे अक्षरों में अंतर) भाषा है.
  • बुनियादी जानकारी देखें - शुरुआती मैप बनाते समय, कुछ सामान्य समस्याएं आती हैं. जैसे:
    • पुष्टि करें कि आपने मैप के विकल्पों में zoom और center प्रॉपर्टी की जानकारी दी है.
    • पक्का करें कि आपने किसी ऐसे div एलिमेंट का एलान किया है जिसमें मैप स्क्रीन पर दिखेगा.
    • सुनिश्चित करें कि मैप के div तत्व की ऊंचाई है. डिफ़ॉल्ट रूप से, div एलिमेंट 0 ऊंचाई के साथ बनाए जाते हैं और इसलिए वे नहीं दिखते हैं.
    पहचान फ़ाइल लागू करने के बारे में जानने के लिए, हमारे उदाहरण देखें.
  • समस्याओं की पहचान करने में मदद पाने के लिए, JavaScript डीबगर का इस्तेमाल करें. जैसे, Chrome डेवलपर टूल में उपलब्ध. सबसे पहले, गड़बड़ियों के लिए JavaScript कंसोल देखें.
  • Stack Overflow पर सवाल पोस्ट करें. अच्छे सवाल पोस्ट करने के तरीके से जुड़े दिशा-निर्देश, सहायता पेज पर उपलब्ध हैं.