Czml Services

These services return Czml for visualization in Cesium.

Cesium is an open source JavaScript globe and map for visualizing dynamic objects and data.

Sgp4 Orbits

The Sgp4 Czml service returns a Czml stream that can be loaded into a Cesium window, or saved as a file. This service provides the orbit for a user-specified satellite, over a given duration.

API Path
vehiclePath/czml/sgp4
HTTP Method
POST
Input Format
{
    "Start": "YYYY-MM-DDTHH:mm:ss",
    "Stop" : "YYYY-MM-DDTHH:mm:ss",
    "SSC": 12345,
    "TLEs": ["TLE string 1","TLE string 2"],
    "PathColor": "Red",
    "LeadTime": 2700,
    "TrailTime": 2700,
    "SatelliteName": "Satellite Name",
    "OutputSettings": (see output POST Data Example)
}
Note: Either the SSC or the TLEs must be specified. If both SSC and TLEs are specified, the TLEs will be used.
Start
The start date and time for the ephemeris.
Stop
The stop date and time for the ephemeris.
SSC
The satellite SSC number as an integer.
TLEs
An array of strings of TLE information.
PathColor
The name of a color to use for the orbit path. Optional, the default is red. The default is used if the name specified is not recognized.
LeadTime
The number of seconds that the orbit path will lead the actual position of the satellite. Optional, the default is 2700.
TrailTime
The number of seconds that the orbit path will follow the actual position of the satellite. Optional, the default is 2700.
SatelliteName
The name of the satellite to display next to the satellite's position along the path. Optional.
OutputSettings
The output settings for this analysis. Optional.
Input Sample

Generates an orbit for the ISS with a green orbit path.

{
    "Start": "2014-07-15T13:02:55",
    "Stop": "2014-07-15T14:02:55",
    "SSC": 25544,
    "PathColor": "Green",
    "SatelliteName": "ISS",
    "OutputSettings": {
        "Step": 300,
        "TimeFormat": "Epoch",
        "CoordinateFormat": {
            "Coord": "XYZ",
            "Frame": "Inertial"
        }
    }
}
Output Sample

The output is a Czml document stream that can be directly used in Cesium.

[
    {
        "id": "document",
        "name": "SGP4 route",
        "description": "Route for a satellite object",
        "version": "1.0",
        "clock":       {
            "interval": "20140715T130255Z/20140715T140255Z",
            "currentTime": "20140715T130255Z"
        }
    },
    {
        "id": "907de8fc-2cfd-41ed-9ad8-1c81146ce7f7",
        "name": "ISS",
        "label": {
            "text": "ISS",
            "scale": 0.5,
            "eyeOffset": {
                "cartesian": [
                    1000,
                    1000,
                    0
                ]
            },
            "fillColor": {
                "rgba": [
                    0,
                    128,
                    0,
                    255
                ]
            }
        },
        "path": {
            "width": 2,
            "leadTime": 2700,
            "trailTime": 2700,
            "material": {
                "polylineOutline": {
                    "color": {
                        "rgba": [
                            0,
                            128,
                            0,
                            255
                        ]
                    }
                }
            }
        },
        "point": {
            "pixelSize": 5,
            "color": {
                "rgba": [
                    0,
                    255,
                    0,
                    255
                ]
            },
            "outlineColor": {
                "rgba": [
                    255,
                    255,
                    255,
                    255
                ]
            },
            "outlineWidth": 1
        },
        "position": {
            "interpolationAlgorithm": "LAGRANGE",
            "interpolationDegree": 5,
            "referenceFrame": "INERTIAL",
            "epoch": "20140715T130255Z",
            "cartesian": [
                0,
                -4523158.946108278,
                4974755.3926670505,
                973796.9219644082,
                300,
                -5483598.473258102,
                3927485.6504392726,
                -819481.5189799711,
                600,
                -5822099.923416168,
                2434745.8688244275,
                -2519573.1542970072,
                900,
                -5500958.93829691,
                666108.8794233681,
                -3933426.426193799,
                1200,
                -4557448.977191549,
                -1177939.650874888,
                -4901041.271107068,
                1500,
                -3098994.8713867627,
                -2888937.858212128,
                -5313358.452854597,
                1800,
                -1290649.589421391,
                -4273782.676854467,
                -5124088.224063983,
                2100,
                663410.8341995103,
                -5176047.322256854,
                -4354598.270790426,
                2400,
                2542457.57322875,
                -5493341.630953689,
                -3091609.989793312,
                2700,
                4133775.7529580663,
                -5189045.694134789,
                -1477839.6869088674,
                3000,
                5256798.781596554,
                -4296946.519933884,
                303782.83779966214,
                3300,
                5783988.569934239,
                -2917815.8451058124,
                2050865.8454086138,
                3600,
                5655669.575847693,
                -1207990.387488192,
                3564872.9572488293
            ]
        }
    }
]

Gps Orbits

The Gps Czml service returns a Czml stream that can be loaded into a Cesium window, or saved as a file. This service provides all of the current Gps satellite orbits for a given time, colored by Gps Block Type. Optionally, the service will highlight those orbits for which the Gps satellite is unhealthy.

API Path
vehiclePath/czml/Gps
HTTP Method
GET
Input Format
    /vehiclePath/Czml/Gps?u=APIKEY&start=YYYY-MM-DDTHH:mm:ss&stop=YYYY-MM-DDTHH:mm:ss&highlightOutages=true&outageColor=White&inertial=false
start
The start date and time for the orbits.
stop
The stop date and time for the orbits.
highlightOutages
If true, those Gps satellites that are unhealthy will have their orbits highlighted using outageColor. Optional, the default value is true.
outageColor
The color to use when highlighting unhealthy Gps satellites. Optional, the default is White. Color names can be found by searching for C# color names on the internet.
inertial
When true, the orbit coordinates are generated using inertial coordinates. When false, the orbit coordinates are generated using Earth-fixed coordinates. Optional, the default is true.
Input Sample
    /vehiclePath/Czml/Gps?u=APIKEY&start=2014-07-15&stop=2014-07-16
Usage Example

To load this Czml directly into a Cesium window, create your Cesium environment first, using the instructions here. Once your Cesium environment is up, add some javascript that will populate the Cesium globe with the Czml from this Url, similar to the following.

    <script>
            var viewer = new Cesium.Viewer('cesiumContainer');
            var czmlDataSource = new Cesium.CzmlDataSource();
            var baseURL = '.../vehiclePath/Czml/Gps?start=';
            var startStr = '2014-07-15';
            var stopStr = '&stop=2014-07-16';
            var highlightStr = '&highlightOutages=true';
            var outageColorStr = '&outageColor=White';
            var url = baseURL + startStr + stopStr + highlightStr + outageColorStr;
            czmlDataSource.loadUrl(url).then(function () {
                viewer.dataSources.add(czmlDataSource);
            })
    </script>

Global Gps Accuracy Czml

The Global Gps Accuracy Czml service returns a Czml stream that can be loaded into a Cesium window, or saved as a file. This service provides global Gps error data, for the GPS constellation on a given date. The data is returned and colored according to the legend below. The service can be used to retrieve static data that shows the 95% confidence, predicted maximum GPS navigation error at each grid point for that date. This data is static and will not change as the Cesium globe moves in time. Alternatively, the service can return the 95% confidence, predicted Gps navigation errors at each time step, at each grid point for that date. This type of data is animated and will change as the Cesium globe is moved in time. Once loaded into a Cesium globe, clicking a specific gridpoint will show the statistics for that site. The statistics for the static data show the maximum error over the entire day.

PACCSm.jpg
API Path
vehiclePath/czml/Gps
HTTP Method
GET
Input Format
    /navigation/predicted/czml/global?u=APIKEY&date=YYYY-MM-DD&animated=false&useSmallGrid=false
date
The date to report Gps global accuracy.
animated
When true, will return the animated GPS errors. When false, the static daily maximum values are returned. Note that when animated is true, this can be a considerable amount of data and may take some time to return. To reduce this time, set useSmallGrid to false. Optional, default is false.
useSmallGrid
When true, global data calculated on a grid of 2x2 degrees is returned. When false, data calculated on a grid of 5x5 degrees is returned. Optional, default is false.
Input Sample
    /navigation/predicted/czml/global?u=APIKEY&date=2014-07-16
Usage Example

To load this Czml directly into a Cesium window, create your Cesium environment first, using the instructions here. Once your Cesium environment is up, add some JavaScript that will populate the Cesium globe with the Czml from this Url, similar to the following.

    <script>
        var viewer = new Cesium.Viewer('cesiumContainer');
        var czmlDataSource = new Cesium.CzmlDataSource();
        var baseURL = '.../navigation/predicted/czml/global?date=';
        var dateStr = '2014-07-16'; // or from user input
        var url = baseURL + dateStr;
        czmlDataSource.loadUrl(url).then(function () {
            $('#legend').show();
            viewer.dataSources.add(czmlDataSource);
        })
    </script>

Airspace Volumes

The Airspace Volumes Czml service returns a Czml stream that can be loaded into a Cesium window, or saved as a file. This service provides graphical volumes representing airspaces used in these services. Volumes can be retrieved by using the airspace search criteria defined in the Defining Airspace Options help section.

API Path
airspace/czml
HTTP Method
POST
Input Format
[
 {
    "AirspaceOptions": {options defined here},
    "Color": "Red",
    "Translucency" : 50,
    "Outline": "true",
    "OutlineColor": "Black",
    "DisplayStart": "2017-01-17T13:02:55",
    "DisplayStop" : "2017-01-17T18:53:43",
 },
 {
 ...
 },
...
]

Note that the input supports an array of request objects; you can request many different types of airspace volumes with one call.

Also note that Cesium does not handle large numbers of czml items well. A few hundred will work fine, whereas several thousand will drop the Cesium frame rate dramatically. It's suggested that you use the airspace filtering capabilities in the 'AirspaceOptions' parameter to make the number of returned czml objects as small as possible. If you were to leave off the optional 'AirspaceOptions', this service will return over 20000 items, which will not be viewable in Cesium at all.

AirspaceOptions
Json object representing the options for selecting airspaces to use in this service. Optional, Airspace options defaults are used. See Defining Airspace Options for more information.
Color
The color for the airspace volume. Optional, the default is red. The default is used if the name specified is not recognized.
Translucency
How transparent the airspace is. Use a number between 0 and 100 inclusive. 0 is invisible, 100 is opaque. Optional, the default is 50.
Outline
Whether the airspace is drawn with outlines. Optional, the default is true.
Outline Color
The color of the outline, if it is drawn. Optional, the default is black. The default is used if the name specified is not recognized.
DisplayStart
The time at which the airspace volume will appear. Optional, the default is DateTime.Min.
DisplayStop
The time at which the airspace volume will disappear. Optional, the default is DateTime.Max.
Input Sample

Returns czml for park airspaces and colors them green. Also returns airport airspaces, coloring them gray. Both are displaying at different times and have different properties.

[
    {
        "AirspaceOptions": {
            "Categories": [ "Parks" ],
            "RegionCenter": {
                "Latitude": 37.13328,
                "Longitude": -76.41104,
                "Altitude": 0
            },
            "MeanSeaLevel": true,
            "UseRegionalAirspaceQuery": true,
            "RegionRadius": 300000
        },
        "Color": "green",
        "OutlineColor": "LimeGreen",
        "DisplayStart": "2017-01-01T01:00:00",
        "DisplayStop": "2017-01-01T06:59:59"
    },
    {
        "AirspaceOptions": {
            "Categories": [ "Airports" ],
            "RegionCenter": {
                "Latitude": 37.13328,
                "Longitude": -76.41104,
                "Altitude": 0
            },
            "MeanSeaLevel": true,
            "UseRegionalAirspaceQuery": true,
            "RegionRadius": 5000
        },
        "Color": "gray",
        "Outline": "false",
        "DisplayStart": "2017-01-01T06:00:00",
        "DisplayStop": "2017-01-01T11:59:59"
    }
]
Output Sample

The output contains a Czml document string that can be directly used in Cesium as well as a list of unrecognized airspaceIds that were sent to the service, if any.

{
    "Czml": "[{\"id\":\"document\",\"name\":\"AirspaceRegions\",\"description\":\"Airspace regions for a set of provided airspace ids\",\"version\":\"1.0\",...truncated for brevity",
    "UnrecognizedIds": []
}