KML और GeoRSS लेयर

KmlLayer, KML और GeoRSS एलिमेंट को Maps JavaScript API के टाइल ओवरले में रेंडर करता है.

खास जानकारी

Maps JavaScript API, भौगोलिक जानकारी दिखाने के लिए KML और GeoRSS डेटा फ़ॉर्मैट के साथ काम करता है. इन डेटा फ़ॉर्मैट को मैप पर दिखाने के लिए, KmlLayer ऑब्जेक्ट का इस्तेमाल किया जाता है. इसके कंस्ट्रक्टर में, सार्वजनिक तौर पर ऐक्सेस की जा सकने वाली KML या GeoRSS फ़ाइल का यूआरएल होता है.

ध्यान दें: Maps JavaScript API में KML ओवरले जनरेट करने वाली KmlLayer क्लास, रेंडर करने के लिए KML फ़ाइलें पाने और पार्स करने के लिए, Google की होस्ट की गई सेवा का इस्तेमाल करती है. इसलिए, KML फ़ाइलों को सिर्फ़ तब दिखाया जा सकता है, जब उन्हें सार्वजनिक रूप से ऐक्सेस किए जा सकने वाले ऐसे यूआरएल पर होस्ट किया गया हो जिसे ऐक्सेस करने के लिए पुष्टि करने की ज़रूरत न हो.

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

Maps JavaScript API, दिए गए भौगोलिक एक्सएमएल डेटा को KML फ़ॉर्मैट में बदलता है. इसके बाद, इसे Maps JavaScript API के टाइल ओवरले का इस्तेमाल करके मैप पर दिखाया जाता है. यह KML, Maps JavaScript API के जाने-पहचाने ओवरले एलिमेंट की तरह दिखता है और कुछ हद तक उसी तरह काम करता है. KML <Placemark> और GeoRSS point एलिमेंट को मार्कर के तौर पर रेंडर किया जाता है. उदाहरण के लिए, <LineString> एलिमेंट को पॉलीलाइन के तौर पर और <Polygon> एलिमेंट को पॉलीगॉन के तौर पर रेंडर किया जाता है. इसी तरह, <GroundOverlay> एलिमेंट को मैप पर आयताकार इमेज के तौर पर रेंडर किया जाता है. हालांकि, अहम बात यह है कि ये ऑब्जेक्ट, Maps JavaScript API Markers, Polylines, Polygons या GroundOverlays नहीं हैं. इसके बजाय, इन्हें मैप पर एक ही ऑब्जेक्ट में रेंडर किया जाता है.

KmlLayer ऑब्जेक्ट, मैप पर तब दिखते हैं, जब उनकी map प्रॉपर्टी सेट कर दी जाती है. इन्हें मैप से हटाने के लिए, setMap() को कॉल करें और null पास करें. KmlLayer ऑब्जेक्ट, इन चाइल्ड एलिमेंट को रेंडर करने की प्रोसेस को मैनेज करता है. इसके लिए, यह मैप के दिए गए बाउंड के हिसाब से सही सुविधाएं अपने-आप वापस लाता है. बाउंड्री बदलने पर, मौजूदा व्यूपोर्ट में मौजूद सुविधाएं अपने-आप रेंडर हो जाती हैं.

KmlLayer में मौजूद कॉम्पोनेंट, ज़रूरत के हिसाब से रेंडर किए जाते हैं. इसलिए, इस लेयर की मदद से हज़ारों मार्कर, पॉलीलाइन, और पॉलीगॉन को आसानी से रेंडर किया जा सकता है. ध्यान दें कि इन कॉम्पोनेंट ऑब्जेक्ट को सीधे तौर पर ऐक्सेस नहीं किया जा सकता. हालांकि, ये सभी क्लिक इवेंट उपलब्ध कराते हैं, जो उन अलग-अलग ऑब्जेक्ट पर डेटा दिखाते हैं.

KML लेयर के विकल्प

KmlLayer() कंस्ट्रक्टर, चाहें तो कई KmlLayerOptions पास कर सकता है:

• map से उस Map के बारे में पता चलता है जिस पर KmlLayer को रेंडर करना है. setMap() तरीके में इस वैल्यू को null पर सेट करके, KmlLayer को छिपाया जा सकता है.
• preserveViewport से पता चलता है कि लेयर दिखाते समय, मैप को KmlLayer के कॉन्टेंट की सीमाओं के हिसाब से अडजस्ट नहीं किया जाना चाहिए. डिफ़ॉल्ट रूप से, KmlLayer दिखाने पर, मैप को ज़ूम किया जाता है और इस तरह से सेट किया जाता है कि लेयर का पूरा कॉन्टेंट दिखे.
• suppressInfoWindows से पता चलता है कि KmlLayer में मौजूद क्लिक की जा सकने वाली सुविधाओं से, InfoWindow ऑब्जेक्ट नहीं दिखने चाहिए.

इसके अलावा, KmlLayer रेंडर होने के बाद, इसमें एक metadata प्रॉपर्टी होती है. इसमें लेयर का नाम, जानकारी, स्निपेट, और लेखक की जानकारी होती है. यह जानकारी, KmlLayerMetadata ऑब्जेक्ट लिटरल में होती है. getMetadata() तरीके का इस्तेमाल करके, इस जानकारी की जांच की जा सकती है. KmlLayer ऑब्जेक्ट को रेंडर करने के लिए, बाहरी सर्वर के साथ एसिंक्रोनस कम्यूनिकेशन की ज़रूरत होती है. इसलिए, आपको metadata_changed इवेंट के लिए सुनना होगा. इससे पता चलेगा कि प्रॉपर्टी भर दी गई है.

नीचे दिए गए उदाहरण में, दिए गए GeoRSS फ़ीड से KmlLayer बनाया गया है:

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: 49.496675, lng: -102.65625 },
    }
  );

  const georssLayer = new google.maps.KmlLayer({
    url:
      "http://api.flickr.com/services/feeds/geo/?g=322338@N20&lang=en-us&format=feed-georss",
  });
  georssLayer.setMap(map);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: 49.496675, lng: -102.65625 },
  });
  const georssLayer = new google.maps.KmlLayer({
    url: "http://api.flickr.com/services/feeds/geo/?g=322338@N20&lang=en-us&format=feed-georss",
  });

  georssLayer.setMap(map);
}

window.initMap = 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>GeoRSS Layers</title>

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

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

यहां दिए गए उदाहरण में, दिए गए KML फ़ीड से KmlLayer बनाने का तरीका बताया गया है:

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 11,
      center: { lat: 41.876, lng: -87.624 },
    }
  );

  const ctaLayer = new google.maps.KmlLayer({
    url: "https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml",
    map: map,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 11,
    center: { lat: 41.876, lng: -87.624 },
  });
  const ctaLayer = new google.maps.KmlLayer({
    url: "https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml",
    map: map,
  });
}

window.initMap = 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>KML Layers</title>

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

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

KML फ़ाइल की सुविधाओं के बारे में जानकारी

KML में कई सुविधाएँ शामिल हो सकती हैं. इसलिए, हो सकता है कि आपको KmlLayer ऑब्जेक्ट से सीधे तौर पर सुविधा का डेटा ऐक्सेस न मिले. इसके बजाय, सुविधाओं को इस तरह से रेंडर किया जाता है कि वे क्लिक किए जा सकने वाले Maps JavaScript API ओवरले की तरह दिखें. किसी सुविधा पर क्लिक करने से, डिफ़ॉल्ट रूप से एक InfoWindow खुलता है. इसमें दी गई सुविधा के बारे में KML <title> और <description> की जानकारी होती है. इसके अलावा, KML फ़ीचर पर क्लिक करने से KmlMouseEvent जनरेट होता है. इससे यह जानकारी मिलती है:

• position से, अक्षांश/देशांतर के उन निर्देशांकों का पता चलता है जहां इस KML फ़ीचर के लिए InfoWindow को ऐंकर करना है. यह आम तौर पर, पॉलीगॉन, पॉलीलाइन, और GroundOverlay के लिए क्लिक की गई जगह होती है. हालांकि, मार्कर के लिए यह सही ऑरिजिन होता है.
• pixelOffset, ऊपर दिए गए position से InfoWindow के “टेल” को ऐंकर करने के लिए ऑफ़सेट दिखाता है. पॉलीगोनल ऑब्जेक्ट के लिए, यह ऑफ़सेट आम तौर पर 0,0 होता है, लेकिन मार्कर के लिए इसमें मार्कर की ऊंचाई शामिल होती है.
• featureData में KmlFeatureData का JSON स्ट्रक्चर होता है.

यहां KmlFeatureData ऑब्जेक्ट का एक सैंपल दिखाया गया है:

{
  author: {
    email: "nobody@google.com",
    name: "Mr Nobody",
    uri: "http://example.com"
  },
  description: "description",
  id: "id",
  infoWindowHtml: "html",
  name: "name",
  snippet: "snippet"
}

नीचे दिए गए उदाहरण में, KML फ़ाइल में मौजूद <Description> टेक्स्ट को दिखाया गया है. जब किसी सुविधा पर क्लिक किया जाता है, तब वह साइड <div> में दिखता है:

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 12,
      center: { lat: 37.06, lng: -95.68 },
    }
  );

  const kmlLayer = new google.maps.KmlLayer({
    url: "https://raw.githubusercontent.com/googlearchive/kml-samples/gh-pages/kml/Placemark/placemark.kml",
    suppressInfoWindows: true,
    map: map,
  });

  kmlLayer.addListener("click", (kmlEvent) => {
    const text = kmlEvent.featureData.description;

    showInContentWindow(text);
  });

  function showInContentWindow(text: string) {
    const sidebar = document.getElementById("sidebar") as HTMLElement;

    sidebar.innerHTML = text;
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: { lat: 37.06, lng: -95.68 },
  });
  const kmlLayer = new google.maps.KmlLayer({
    url: "https://raw.githubusercontent.com/googlearchive/kml-samples/gh-pages/kml/Placemark/placemark.kml",
    suppressInfoWindows: true,
    map: map,
  });

  kmlLayer.addListener("click", (kmlEvent) => {
    const text = kmlEvent.featureData.description;

    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    const sidebar = document.getElementById("sidebar");

    sidebar.innerHTML = text;
  }
}

window.initMap = initMap;
index.js

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

#container {
  height: 100%;
  display: flex;
}

#sidebar {
  flex-basis: 15rem;
  flex-grow: 1;
  padding: 1rem;
  max-width: 30rem;
  height: 100%;
  box-sizing: border-box;
  overflow: auto;
}

#map {
  flex-basis: 0;
  flex-grow: 4;
  height: 100%;
}
style.css

<html>
  <head>
    <title>KML Feature Details</title>

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

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

KML रेंडरिंग के लिए, साइज़ और जटिलता से जुड़ी पाबंदियां

Maps JavaScript API में, लोड की गई KML फ़ाइलों के साइज़ और जटिलता से जुड़ी सीमाएं होती हैं. मौजूदा सीमाओं की खास जानकारी यहां दी गई है.

ध्यान दें: इन सीमाओं में किसी भी समय बदलाव किया जा सकता है.

प्राप्त अधिकतम फ़ाइल आकार (सामान्य KML, सामान्य GeoRSS, या संपीडित KMZ)

3MB

अधिकतम असंपीडित KML फ़ाइल आकार

10MB

KMZ फ़ाइलों में, कंप्रेस न की गई इमेज फ़ाइल का ज़्यादा से ज़्यादा साइज़

हर फ़ाइल के लिए 500 केबी

नेटवर्क लिंक की ज़्यादा से ज़्यादा संख्या

10

पूरे दस्तावेज़ में अधिकतम विशेषताओं की संख्या

1,000

KML लेयर की संख्या

एक Google मैप पर, KML लेयर की एक तय संख्या ही दिखाई जा सकती है. अगर इस सीमा से ज़्यादा लेयर जोड़ी जाती हैं, तो मैप पर कोई भी लेयर नहीं दिखेगी. साथ ही, आपके वेब ब्राउज़र के JavaScript कंसोल में गड़बड़ी की सूचना दी जाएगी. यह सीमा, KmlLayer क्लास की संख्या और उन लेयर को बनाने के लिए इस्तेमाल किए गए सभी यूआरएल की कुल लंबाई के आधार पर तय की जाती है. हर नई KmlLayer बनाने पर, वह लेयर के लिए तय की गई सीमा का कुछ हिस्सा इस्तेमाल करेगी. साथ ही, यह सीमा का कुछ और हिस्सा भी इस्तेमाल करेगी. यह इस बात पर निर्भर करता है कि KML फ़ाइल को किस यूआरएल से लोड किया गया था. इसलिए, जोड़े जा सकने वाली लेयर की संख्या हर ऐप्लिकेशन के हिसाब से अलग-अलग होगी. औसतन, आपको सीमा तक पहुंचे बिना 10 से 20 लेयर लोड करने की सुविधा मिलनी चाहिए. अगर इसके बाद भी सीमा पूरी हो जाती है, तो KML यूआरएल को छोटा करने के लिए, यूआरएल छोटा करने वाले टूल का इस्तेमाल करें. इसके अलावा, अलग-अलग KML यूआरएल के लिए NetworkLinks वाली एक KML फ़ाइल बनाएं.

परफ़ॉर्मेंस और कैश मेमोरी से जुड़ी बातें

Google के सर्वर, KML फ़ाइलों को कुछ समय के लिए कैश मेमोरी में सेव करेंगे, ताकि आपके सर्वर पर लोड कम हो सके. इससे आपके उपयोगकर्ताओं के लिए परफ़ॉर्मेंस भी बेहतर होगी. ऐसा इसलिए, क्योंकि आपकी KML फ़ाइल के सही सेगमेंट को स्पेस-इफ़िशिएंट तरीके से दिखाया जाएगा. ऐसा तब होगा, जब आपके उपयोगकर्ता मैप पर क्लिक करेंगे, उसे पैन करेंगे, और ज़ूम करेंगे.

बेहतर परफ़ॉर्मेंस के लिए, हमारा सुझाव है कि आप:

• KML में सही <expires> टैग का इस्तेमाल करें.
  
  KmlLayer, KML फ़ाइलों को कैश मेमोरी में सेव करने का तरीका तय करते समय, एचटीटीपी हेडर का इस्तेमाल नहीं करेगा.
• अनुरोध के समय, फ़ाइलों को डाइनैमिक तौर पर जनरेट न करें.
  
  इसके बजाय, फ़ाइलों को पहले से जनरेट करके रख लें, ताकि ज़रूरत पड़ने पर उन्हें स्टैटिक तरीके से उपलब्ध कराया जा सके. अगर आपके सर्वर को KML फ़ाइल ट्रांसमिट करने में ज़्यादा समय लगता है, तो हो सकता है कि KmlLayer न दिखे.
• जब तक आपको यह पक्का न पता हो कि आपकी फ़ाइल अपडेट हो गई है, तब तक कैश मेमोरी को बायपास करने की कोशिश न करें.
  
  कैश मेमोरी को हमेशा बायपास करने से, आपके सर्वर पर दबाव बढ़ सकता है. उदाहरण के लिए, अगर आपकी साइट अचानक लोकप्रिय हो जाती है और आपको बड़े KML फ़ाइलें दिखानी हैं, तो ऐसा हो सकता है. कैश मेमोरी को बायपास करने के लिए, क्वेरी पैरामीटर के तौर पर कोई रैंडम नंबर या उपयोगकर्ता के डिवाइस का समय जोड़ा जा सकता है.
  
  अगर किसी उपयोगकर्ता की घड़ी का समय गलत है और <expires> टैग को सही तरीके से सेट नहीं किया गया है, तो इससे कैश मेमोरी में मौजूद पुराना डेटा उपयोगकर्ताओं को दिख सकता है.
  
  इसके बजाय, अपडेट की गई स्टैटिक फ़ाइलों को नए और अलग-अलग वर्शन नंबर के साथ पब्लिश करें. साथ ही, सर्वर-साइड कोड का इस्तेमाल करके, KmlLayer को पास किए गए यूआरएल को डाइनैमिक तौर पर अपडेट करें.
• KML फ़ाइलों में बदलाव, हर मिनट में सिर्फ़ एक बार करें.
  
  अगर सभी फ़ाइलों का कुल साइज़ (बिना कंप्रेस किए) 1 एमबी से ज़्यादा है, तो हर पांच मिनट में सिर्फ़ एक बार बदलाव करें.
• जियोस्पेशल डेटा सर्वर का इस्तेमाल करते समय, लेयर के व्यूपोर्ट को सीमित करने के लिए क्वेरी पैरामीटर का इस्तेमाल न करें.
  
  इसके बजाय, bounds_changed इवेंट का इस्तेमाल करके, मैप के व्यूपोर्ट को सीमित किया जा सकता है. उपयोगकर्ताओं को सिर्फ़ ऐसी सुविधाएं भेजी जाएंगी जो अपने-आप दिख सकती हैं.
  
  अगर आपके जियोस्पेशल डेटा सर्वर में बहुत ज़्यादा डेटा है, तो डेटा लेयर का इस्तेमाल करें.
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
• जियोस्पेशल डेटा सर्वर का इस्तेमाल करते समय, उन सुविधाओं के हर ग्रुप के लिए कई KmlLayer का इस्तेमाल करें जिन्हें उपयोगकर्ताओं को टॉगल करने की अनुमति देनी है. इसके बजाय, अलग-अलग क्वेरी पैरामीटर के साथ एक KmlLayer का इस्तेमाल करें.
• फ़ाइल का साइज़ कम करने के लिए, कंप्रेस की गई KMZ फ़ाइलों का इस्तेमाल करें.
• अगर Google Cloud Storage या किसी अन्य क्लाउड स्टोरेज समाधान का इस्तेमाल किया जा रहा है, तो ऐक्सेस कंट्रोल लागू करने के लिए, हस्ताक्षर किए गए यूआरएल या अस्थायी टोकन जैसी सुविधाओं का इस्तेमाल न करें. इनकी वजह से, अनजाने में कैश मेमोरी में सेव होने से रोका जा सकता है.
• सभी पॉइंट की सटीक जानकारी को सही जानकारी में बदलें.
• मिलते-जुलते फ़ीचर की ज्यामिति को मर्ज करें और आसान बनाएं. जैसे, पॉलीगॉन और पॉलीलाइन.
• इस्तेमाल नहीं किए गए किसी भी एलिमेंट या इमेज रिसॉर्स को हटाएं.
• इस्तेमाल नहीं किए जा सकने वाले एलिमेंट हटाएं.

अगर आपको निजी डेटा ऐक्सेस करना है, कैश मेमोरी में सेव होने से रोकना है या ब्राउज़र के व्यूपोर्ट को क्वेरी पैरामीटर के तौर पर जियोस्पेशल डेटा सर्वर पर भेजना है, तो हमारा सुझाव है कि KmlLayer के बजाय डेटा लेयर का इस्तेमाल करें. इससे आपके उपयोगकर्ताओं के ब्राउज़र, सीधे आपके वेब सर्वर से संसाधनों का अनुरोध कर पाएंगे.

KML के साथ काम करने वाले एलिमेंट

Maps JavaScript API, इन KML एलिमेंट के साथ काम करता है. सामान्य रूप से, समझ नहीं आने पर KML पार्सर, XML टैग को चुपचाप अनदेखा करता है.

• प्लेसमार्क
• आइकन
• फ़ोल्डर
• जानकारी देने वाला एचटीएमएल—<BalloonStyle> और <text> के ज़रिए इकाई को बदलना
• KMZ (संलग्न चित्र सहित संपीडित KML)
• बहुरेखा तथा बहुभुज
• रंग, भराव तथा अपारदर्शिता सहित बहुरेखाओं व बहुभुजों के लिए शैलियां
• डेटा को डायनॉमिक तरीके से आयात करने के लिए नेटवर्क लिंक
• ग्राउंड ओवरले तथा स्क्रीन ओवरले

यहां दी गई टेबल में, इस्तेमाल किए जा सकने वाले KML एलिमेंट के बारे में पूरी जानकारी दी गई है.