Keyhole Markup Language

Sky Data in KML

You can now create KML files that display objects in the sky, such as stars, constellations, planets, the Earth's moon, and galaxies. This page explains how to create a KML file to display celestial data in Google Sky. Specifically, you'll need to do the following:

  • Add a hint attribute to the <kml> element at the beginning of your KML file that indicates the file contains sky data, not Earth data
  • Convert celestial coordinates to Earth-based KML coordinates

Sky Mode

The Google Earth user can control when to switch to Sky mode, using the View > Switch to Sky menu option or the Sky button in the user interface. When the user switches to Sky mode, Google Earth transitions to show images of the sky photographed from telescopes around the world and inouter space. The view of the sky is as if the user is standing at the center of the Earth, looking outward toward the heavens. This model allows users to explore the sky above their heads as well as parts of the celestial sphere that would normally be seen only from the other side of the Earth.


Celestial coordinates are described in terms of right ascension (RA) and declination. Right ascension, which corresponds to longitude, represents a distance from the point in the sky where the sun crosses the celestial equator at the vernal equinox. Right ascension is measured from 0 to 24 hours, with one hour of RA equal to the amount the sky rotates above a given point on the Earth's surface in one hour of time. Zero hours of RA is at the point of the vernal equinox, with RA increasing eastward from that point.

Declination is analogous to latitude, with 0 degrees declination located at the celestial equator. Declination values range from −90° directly above the South Pole to +90° directly above the North Pole.

The following figure shows Google Sky with grid lines for right ascension and declination turned on:


Supported Elements

The following elements are supported in Google Earth 4.2, Sky mode:

  • Placemark
  • Ground Overlay
  • LineString
  • Polygon
  • MultiGeometry
  • LinearRing
  • Point
  • Style elements
  • Container elements

Note, however, that <tilt> and <roll> are currently ignored in these elements.

The hint attribute

If your KML file contains Sky data, be sure to add the hint attribute to the <kml> element at the beginning of the file:

<kml xmlns="http://www.opengis.net/kml/2.2" hint="target=sky">

When a file with the "target=sky" hint is loaded, Google Earth prompts the user to switch to Sky view if it is not already in this mode.

Converting Celestial Coordinates for Display in Google Earth

You'll need to perform some simple calculations to convert right ascension coordinates (Hours/Minutes/Seconds) into degrees of longitude so that the data displays correctly in Google Earth (Sky mode).

Convert Right Ascension Coordinates

To convert right ascension coordinates from values in a range from 0 to 24 to values in the range from −180 ° to +180 °, use this formula, where hour, minute, and second are the original right ascension values of the data:

(hour + minute/60 + second/3600)*15 − 180

Convert Declination Coordinates

Declination coordinates correspond directly to latitude values, ranging from −90° south of the celestial equator to +90° north of the celestial equator.

Calculating Range for the LookAt Element

When you use the <LookAt> element with sky data, you will need to perform the following calculations to determine the range. The basic formula is as follows:

r = R*(k*sin(β/2) - cos(β/2) + 1)


is the range, specified in the <LookAt> element
is the radius of the celestial sphere (or, in this case, the Earth, since we're effectively inside it looking out at the sky), which is equal to 6.378 x 106
is equal to 1/tan(α/2), or 1.1917536
is the angular extent of the view in Google Earth when the camera is pulled back to the center of the celestial sphere (Earth)
is the desired arc seconds of your sky image

Note: The Google Calculator is a handy tool for making such calculations.

Here are some sample ranges:

  • Large spiral galaxy (Sunflower Galaxy): 20-30 km
  • Large globular cluster (M15): 20-30 km
  • Andromeda Galaxy: 200 km
  • Planetary Nebula (Owl Nebula): 5-10 km
  • Large Nebula (Trifid Nebula): 10-30 km
  • Single Hubble Pointing (Seyfert's Sextet): 2-5 km
  • Open star cluster (Praesepe): 30-60 km
  • Smaller spiral galaxy: 5-10 km
  • Large Magellanic Cloud: 400-500 km

Saving Files in Google Earth

In Google Earth, if you are in Sky mode and you save a file, Google Earth assumes you want to save the file as a Sky file, so it adds the hint attribute to the <kml> element automatically.


Here is an example of creating a KML file that shows the Crab Nebula in Google Earth:

<kml xmlns="http://www.opengis.net/kml/2.2" hint="target=sky">
<Style id="CrabNebula">
</Style> <Placemark>
<name>Crab Nebula</name>
This is the Crab Nebula. It is the remnant of a supernovae that was
observed on Earth in 1054 CE. You can find out more about the Crab
Nebula by looking at the information in the default layers, specifically:
<li> <b>Backyard Astronomy</b>
<li> <b>Hubble Showcase</b>
<li> <b>Life of a Star</b>
Enjoy exploring Sky!
</Point> </Placemark>

Here is how this file appears in Google Earth:

screen capture from Google Earth