go-satellite: A Go port of SGP4 for TLE-based orbit propagation

What go-satellite solves and who it targets

go-satellite addresses a narrow problem: computing the position and velocity of an Earth-orbiting satellite from a two-line element set (TLE) at a given time. It is a direct port of the SGP4 library into Go, done by the author as an early Go project. The intended user is a Go developer who needs orbital mechanics without pulling in a large dependency tree. The README lists functions for TLE parsing, propagation, and coordinate transforms, which suggests the library is aimed at applications like ground station pass prediction, telemetry visualization, or educational tools. It is not a full orbital mechanics suite; it focuses on the SGP4 model and the conversions needed to turn ECI coordinates into Earth-fixed or observer-relative frames.

The SGP4 mechanism and what the API actually gives you

The core is the SGP4 propagator, which takes a TLE and a time and returns a Vector3 position and velocity in Earth-Centered Inertial (ECI) coordinates. The README shows two entry points: ParseTLE, which parses the two lines into a Satellite struct, and TLEToSat, which parses and then runs sgp4init. The Propagate function then computes the state at a given date and time. Beyond that, the library provides coordinate conversions: ECIToLLA for latitude, longitude, altitude and velocity, ECIToECEF for Earth-fixed coordinates, and ECIToLookAngles for azimuth, elevation and range from an observer. There is also LLAToECI to go the other way. The presence of GSTimeFromDate and ThetaG_JD indicates the library computes Greenwich Mean Sidereal Time internally, which is necessary for those transforms. The API is deliberately small, with no configuration beyond a Gravity constant passed to the parsing functions.

Getting it running: commands and configuration

The README does not include a go get command, but the import path is github.com/joshuaferrara/go-satellite, so a standard go get github.com/joshuaferrara/go-satellite would fetch it. The package exposes constants like DEG2RAD and RAD2DEG for angle conversions. To use it, you would call TLEToSat with two TLE lines and a gravity constant, then call Propagate with a satellite and a date. For example, you would construct a Satellite struct with Line1 and Line2 strings, or use ParseTLE to do that for you. The Spacetrack type provides a way to fetch TLEs from the Space-Track API, initialized with a username and password, and GetTLE takes a catalog ID, time, and gravity constant to return an initialized Satellite. There is no mention of build tags, environment variables, or external dependencies beyond the Go standard library, based on the README.

Limitations and failure modes in practice

The most obvious limitation is the maintenance status: the last push was June 2022, and only one release, v0.1.0, exists. The README says the author wrote it as an early Go project, which raises questions about the maturity of the SGP4 implementation. SGP4 has known accuracy limits for very low orbits or long propagation intervals, and the README does not state any operational envelope. The test suite is mentioned, but its coverage is not described. A concrete failure mode is that the Propagate function takes separate integer arguments for year, month, day, hours, minutes, and seconds, which is error-prone and does not handle fractional seconds. Also, the Spacetrack API integration may break if Space-Track changes its authentication or response format, and the library has not been updated to reflect any such changes. For a production system, these are significant risks.

The alternative: using a maintained SGP4 library or a wrapper

The main alternative is to use a more actively maintained SGP4 implementation in Go, such as the one from the go-astrodynamics group or a direct binding to the official C++ SGP4 library. The difference in approach is that go-satellite is a self-contained port, while alternatives often wrap or reimplement the official Vallado code with regular updates. For example, the official SGP4 library has been revised over decades, and a port that does not track those revisions may miss bug fixes or accuracy improvements. Another approach is to use a higher-level library like go-satellite's own Spacetrack for fetching TLEs, but that is still tied to this codebase. If you need long-term reliability, you would compare the accuracy of go-satellite's output against a known reference, which the README does not provide. The choice is between a simple, frozen API and a more complex but maintained codebase.

Maintenance and license considerations

The project is licensed under BSD-2-Clause, which permits commercial use with attribution and no copyleft obligations. That is a permissive license, so you can vendor the code without legal friction, but you should read the license text yourself. The maintenance cost is real: with no commits since June 2022, the repository is effectively dormant. There is no indication of a contributor base or issue tracker activity in the provided material. Upgrading to a newer version is not a concern because there is no newer version. However, you must consider that the SGP4 model itself is stable, so the code may still work for years. The risk is not in the algorithm but in the surrounding ecosystem: Go's standard library may change, and the Spacetrack API may evolve. If you adopt this, you take on the responsibility of patching any issues yourself. The test suite is the only safety net, and you should run it against your own TLEs before trusting the output.

Editorial conclusion

Adopt go-satellite if you need a minimal, dependency-free SGP4 implementation in Go for basic TLE propagation and coordinate conversion, and you are comfortable with a project that has not been updated since mid-2022. Do not use it if you require ongoing maintenance, active community support, or a guarantee of accuracy beyond the included test suite. Before adopting, verify the test suite covers your expected TLE formats and time ranges, and check the repository's open issues for any known propagation edge cases.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes