KML Time Functions

Introduction

To allow temporal mapping, all features written to the KML format can be assigned a number of time-related attributes. In this example, the KMLTimeSetter is used to associate features with a single timestamp (i.e., this feature corresponds to time X). It shows how to animate the movement of a vehicle along a path.

Any feature (point or line) in KML can have time data associated with it. KML data has two time elements:

• TimeStamp - specifies a single moment for a feature
• TimeSpan - specifies a <begin> and <end> time for a feature.

KML time data adheres to the standard dateTime value defined in the XML specification available at https://www.w3.org

For example, an XML dateTime value of:

2021-05-22T15:41:00-08:00

…equates to:

3:41 pm (Pacific Standard Time) on the 22nd May 2021.

In fact, the time component of this is not obligatory. Equally valid is:

2021-05-22

Note the 1 or 2 digit month & day – 2021-5-22 is not valid, use only 2 digits.

FME does not validate KML dates to provide a warning or error in the log. The only way to find that there is a problem is when you open the dataset within Google Earth. To reduce problems use the DateTimeConverter transformer to construct dates in FME in either the FME DateTime format or the XML Schema time format.

Step-by-step Instructions

1. Read in JSON Dataset

Open a blank workspace in FME Workbench. Add JSON reader to the canvas and browse to the electriccartrack.json dataset, which can be downloaded from the Files section of this article. Set the Coord. System to LL84 and click OK. 

As of FME 2025.2, the Coordinate System parameter is now configured within the Parameters dialog of each reader/writer format. For more information, including details about the change and affected transformers, please see Coordinate System Parameter Location Change.

2. Create Points

The input dataset contains latitude and longitude values, which we will use to create points. Add a VertexCreator to the canvas and connect it to the JSONFeature reader feature type. In the parameters, set the X Value to longitude, and the Y Value to latitude. 

3. Covert Time Attribute

KML formats can only accept data in the XML dateTime structure, ISO DateTime (%Y-%m-%dT%H:%M:%S). The input data contains date values in a different format, so we will have to format them. Add a DateTimeConverter to the canvas and connect it to the VertexCreator. In the parameters, set the Datetime Attributes to current_time and the Output Format to ISO (auto format). 

Note: Setting Output Format to FME should generate the same result.
 
4. Create KML Timestamp

Next, we will need to create a KML timestamp with the newly converted time attribute. Add a KMLTimeSetter to the canvas and connect it to the DateTimeCoverter. In the parameters, set the Timestamp to the current_time attribute. 

5. Style KML Point Features

To style the points, we will use the KMLStyler. Add a KMLStyler to the canvas and connect it to the KMLTimeSetter. In the parameters, expand the Icon section, then click on the ellipsis next to Name to open the icon list. Click on the first folder icon to open up the gme icons, then find the gx_cabs icon and click OK twice. 

6. Write Out to OGC/Google KML

Our data is now ready to be written out. Add an OGC/Google KML writer to the canvas. Browse to a location to save the dataset and name it ElectricCarTrack.kml. Connect the writer feature type to the KMLStyler. 

7. View the Results in Google Earth

Run the workspace, then view the output dataset in Google Earth. 

Working with the Animation in Google Earth

When a KML dataset contains TimeStamp or TimeSpan tags, Google Earth automatically detects these and adds extra controls for managing the display. Google Earth automatically selects the beginning and ending for the time slider based on the earliest and latest time found on features in the file. 
To use this functionality, drag the right-hand slider just before 11 pm. 

Then drag the left-hand slider shortly before it.

The default speed for the animation is very fast. To slow it down, click on the wrench icon and change the Animation Speed to the slower end.

Finally, click the play button to run the animation. 

Data Attribution

The data used here originates from open data made available by the City of Vancouver, British Columbia. It contains information licensed under the Open Government License - Vancouver.