CZML vs. Entity API


I’m in the very beginning of migration off Google Earth to Cesium and want to make a right bet.

I explored CZML and Entity API a bit and found CZML to be superior:

  • declarative (while entity creation looks almost the same, further manipulations through the API are imperative)

  • can be created both on the server and on the client

  • automatically merges new data into the current state (so we can either redefine something completely or update some properties or just add more samples - whatever we see fit - all through the same interface)

Then, what is the point of Entity API at all? What are its advantages over CZML?

Which one will enjoy developers’ attention?

Thank you.

It all depends on your use case. I think they can be broadly split into 2 categories, creating/loading the data and manipulating/interrogating the data.

External data or in app data creation:

  1. In general, if you control the web-services or ahead-of-time data generation for your application, then CZML is usually going to be the best choice for getting that visualization into Cesium.

  2. If you are retrieving data from existing web-services or external formats that you don’t control, then reading them directly into the Entity API is often a better solution then pre-converting them to CZML (assuming the format is not too difficult to read with JavaScript). We define a standard DataSource interface you can implement for use cases like this.

  3. If you are creating data on the fly within a Cesium application, then the Entity API is the better choice. You shouldn’t be creating CZML strings client side just to process them with CzmlDataSource. It will technically work, but it’s an incredibly inefficient way to get data into Cesium.

Interrogation and manipulation:

Many use cases involve manipulating and interrogating data after is it loaded. CZML support is actually built on top of the Entity API, so is support for GeoJSON, TopoJSON, (and soon KML). This means that once you load data in these formats, they get turned into Entity instances that you can further manipulate within your app. For example, it would be trivial to make all Polygons blue, without having to worry about whether I’m dealing with a CZML, KML, or GeoJSON defined polygon.

The Entity API also has mechanisms for listening to changes so that you could build custom UI on top of Cesium as well other helpful features (like viewer.zoomTo(entity). Essentially anything you do with data AFTER it is loaded is definitely in the realm of the Entity API.

The Entity API and CZML are both first class citizens in Cesium and almost anything I can think of on the input side of the Entity API will ultimately be supported in CZML as well. Since CZML is built on the Entity API, we usually add a feature to both simultaneously (or close to it). I will admit that right now CZML is lagging behind a little in some areas (not all shape and volume types have CZML support yet) but that’s mainly because we are concentrating on KML right now; and also just went through a huge Entity API refactoring. I expect in a few months CZML will get a lot of attention again.

I hope that clears things up, eventually I plan on turning this information into a blog post to help others understand the different layers of Cesium.



I do control the server, but still load the data in some format, manipulate it, load into Cesium and then adjust according to user interactions.

Creating an entity is almost the same for both CZML and Entity API - you just pass in a plain JS object.

What I really miss from Entity API is an ability to merge new/changed data into an existing entity like CZML does.

Such an ability provides for very simple programming model - one can use the only (pure) function generating JS object for all creating an entity, modifying it or adding more data samples. Or split it into one providing object position and another controlling visual representation.

Can we possibly have the same merge behaviour instead of an exception when entity IDs match?