# KmlDataSource

#### new Cesium.KmlDataSource(options)
engine/Source/DataSources/KmlDataSource.js 3532

A `DataSource` which processes Keyhole Markup Language 2.2 (KML).

KML support in Cesium is incomplete, but a large amount of the standard, as well as Google's `gx` extension namespace, is supported. See Github issue #873 for a detailed list of what is and isn't supported. Cesium will also write information to the console when it encounters most unsupported features.

Non visual feature data, such as `atom:author` and `ExtendedData` is exposed via an instance of `KmlFeatureData`, which is added to each `Entity` under the `kml` property.

Name | Type | Description
--- | --- | ---
`options` | KmlDataSource.ConstructorOptions | optional Object describing initialization options

##### Example:

    const viewer = new Cesium.Viewer('cesiumContainer');
    viewer.dataSources.add(Cesium.KmlDataSource.load('../../SampleData/facilities.kmz',
         {
              camera: viewer.scene.camera,
              canvas: viewer.scene.canvas
         })
    );

##### Demo:

- Cesium Sandcastle KML Demo

##### See:

- Open Geospatial Consortium KML Standard
- Google KML Documentation

### Members

#### camera : Camera|undefined
engine/Source/DataSources/KmlDataSource.js 3567

The position and orientation of this `Camera` will be used to populate various camera parameters when making network requests. Camera movement will determine when to trigger NetworkLink refresh if `viewRefreshMode` is `onStop`.

#### canvas : HTMLCanvasElement|undefined
engine/Source/DataSources/KmlDataSource.js 3557

The current size of this Canvas will be used to populate the Link parameters for client height and width.

#### changedEvent : Event
engine/Source/DataSources/KmlDataSource.js 3666

Gets an event that will be raised when the underlying data changes.

#### clock : DataSourceClock
engine/Source/DataSources/KmlDataSource.js 3636

Gets the clock settings defined by the loaded KML. This represents the total availability interval for all time-dynamic data. If the KML does not contain time-dynamic data, this value is undefined.

#### clustering : EntityCluster
engine/Source/DataSources/KmlDataSource.js 3731

Gets or sets the clustering options for this data source. This object can be shared between multiple data sources.

#### credit : Credit
engine/Source/DataSources/KmlDataSource.js 3749

Gets the credit that will be displayed for the data source

#### entities : EntityCollection
engine/Source/DataSources/KmlDataSource.js 3646

Gets the collection of `Entity` instances.

#### errorEvent : Event
engine/Source/DataSources/KmlDataSource.js 3676

Gets an event that will be raised if an error is encountered during processing.

#### isLoading : boolean
engine/Source/DataSources/KmlDataSource.js 3656

Gets a value indicating if the data source is currently loading data.

#### kmlTours : Array.<KmlTour>
engine/Source/DataSources/KmlDataSource.js 3759

Gets the KML Tours that are used to guide the camera to specified destinations on given time intervals.

#### loadingEvent : Event
engine/Source/DataSources/KmlDataSource.js 3686

Gets an event that will be raised when the data source either starts or stops loading.

#### name : string
engine/Source/DataSources/KmlDataSource.js 3618

Gets or sets a human-readable name for this instance. This will be automatically be set to the KML document name on load.

#### refreshEvent : Event
engine/Source/DataSources/KmlDataSource.js 3696

Gets an event that will be raised when the data source refreshes a network link.

#### show : boolean
engine/Source/DataSources/KmlDataSource.js 3716

Gets whether or not this data source should be displayed.

#### unsupportedNodeEvent : Event
engine/Source/DataSources/KmlDataSource.js 3706

Gets an event that will be raised when the data source finds an unsupported node type.

### Methods

#### static Cesium.KmlDataSource.load(data, options) → Promise.<KmlDataSource>
engine/Source/DataSources/KmlDataSource.js 3605

Creates a Promise to a new instance loaded with the provided KML data.

Name | Type | Description
--- | --- | ---
`data` | Resource | string | Document | Blob | A url, parsed KML document, or Blob containing binary KMZ data or a parsed KML document.
`options` | KmlDataSource.ConstructorOptions | optional An object specifying configuration options

##### Returns:

A promise that will resolve to a new KmlDataSource instance once the KML is loaded.

#### destroy()
engine/Source/DataSources/KmlDataSource.js 3859

Cleans up any non-entity elements created by the data source. Currently this only affects ScreenOverlay elements.

#### load(data, options) → Promise.<KmlDataSource>
engine/Source/DataSources/KmlDataSource.js 3774

Asynchronously loads the provided KML data, replacing any existing data.

Name | Type | Description
--- | --- | ---
`data` | Resource | string | Document | Blob | A url, parsed KML document, or Blob containing binary KMZ data or a parsed KML document.
`options` | KmlDataSource.LoadOptions | optional An object specifying configuration options

##### Returns:

A promise that will resolve to this instances once the KML is loaded.

#### update(time) → boolean
engine/Source/DataSources/KmlDataSource.js 4043

Updates any NetworkLink that require updating.

Name | Type | Description
--- | --- | ---
`time` | JulianDate | The simulation time.

##### Returns:

True if this data source is ready to be displayed at the provided time, false otherwise.

### Type Definitions

#### Cesium.KmlDataSource.ConstructorOptions
engine/Source/DataSources/KmlDataSource.js 3482

Options for constructing a new KmlDataSource, or calling the static `load` method.

##### Properties:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`camera` | Camera | <optional> |  | The camera that is used for viewRefreshModes and sending camera properties to network links.
`canvas` | HTMLCanvasElement | <optional> |  | The canvas that is used for sending viewer properties to network links.
`credit` | Credit | string | <optional> |  | A credit for the data source, which is displayed on the canvas.
`sourceUri` | string | <optional> |  | Overrides the url to use for resolving relative links and other KML network features.
`clampToGround` | boolean | <optional> | false | true if we want the geometry features (Polygons, LineStrings and LinearRings) clamped to the ground.
`ellipsoid` | Ellipsoid | <optional> | Ellipsoid.default | The global ellipsoid used for geographical calculations.
`screenOverlayContainer` | Element | string | <optional> |  | A container for ScreenOverlay images.

#### Cesium.KmlDataSource.LoadOptions
engine/Source/DataSources/KmlDataSource.js 3471

Initialization options for the `load` method.

##### Properties:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`sourceUri` | string | <optional> |  | Overrides the url to use for resolving relative links and other KML network features.
`clampToGround` | boolean | <optional> | false | true if we want the geometry features (Polygons, LineStrings and LinearRings) clamped to the ground.
`ellipsoid` | Ellipsoid | <optional> | Ellipsoid.default | The global ellipsoid used for geographical calculations.
`screenOverlayContainer` | Element | string | <optional> |  | A container for ScreenOverlay images.

Need help? The fastest way to get answers is from the community and team on the Cesium Forum.