Vis-viva calculator
With μ of 398600.4418 km³/s², a distance of 7000 km and a semi-major axis of 10000 km, the orbital speed is 8.60382451787 km/s. Enter the three values in one unit system to get the speed at that point. Free in your browser.
- Free
- Runs in your browser
- No sign-up
- Your data stays on your device
Run — free
Worked example
- Gravitational parameter
- 398,600.4418
- Current radius
- 7,000
- Semi major axis
- 10,000
- Orbital speed
- 8.6038245179
- Speed squared
- 74.0257963343
The vis-viva equation calculator finds an object's instantaneous orbital speed from the primary body's gravitational parameter, the object's current distance from that primary, and the orbit's semi-major axis. It works for elliptical trajectories, including circular orbits as a special case, and for hyperbolic escape trajectories when the semi-major axis is negative. Enter all distances in one consistent unit system and the returned speed will use the corresponding distance-per-time unit. The calculation is deterministic and reports invalid geometries instead of returning an imaginary speed.
Choose one consistent system of units
The vis-viva relationship is compact, but its inputs must share a coherent unit system. Supply the standard gravitational parameter, commonly written as mu, in distance cubed per time squared. Supply the current radius and semi-major axis in that same distance unit.
For example, if mu is expressed in cubic kilometers per second squared and both distances are in kilometers, orbital speed is returned in kilometers per second and speed squared is in square kilometers per square second. SI inputs using meters produce meters per second. The calculator does not attach or convert units because a bare numerical gravitational parameter cannot reveal whether it represents kilometers, meters, seconds, hours, or another consistent choice.
Current radius means distance from the center of the primary body, not altitude above its surface. Semi-major axis describes the whole conic orbit rather than the object's current location. A positive value represents an ellipse, with a circle as the case where radius equals semi-major axis.
A negative value represents a hyperbola. Keeping these definitions distinct prevents the most common input mistakes and makes the result directly usable in mission calculations or independent checks.
Understand how the speed is calculated
The calculator evaluates v = sqrt(mu × (2/r − 1/a)), where v is orbital speed, mu is the gravitational parameter, r is current radius, and a is semi-major axis. This form follows from conservation of specific orbital energy: the object's kinetic energy changes with position while the total energy associated with its orbit remains fixed. On an ellipse, speed is greatest near periapsis, where radius is smallest, and lowest near apoapsis, where radius is largest.
When radius equals semi-major axis, the expression reduces to the familiar circular-orbit result sqrt(mu/r). For a hyperbolic trajectory, a is negative, so subtracting 1/a adds a positive term and produces a speed above the local escape threshold. The response includes both orbital speed and speed squared, which is useful when another calculation needs the energy-like quantity without taking and then squaring a root.
The formula reports speed magnitude only; it does not determine a velocity direction, flight-path angle, inclination, or position in an inertial reference frame.
Recognize invalid orbital geometry
Every division in the equation has a physical meaning, so zero distances are rejected explicitly. A zero current radius would place the object at the mathematical center of the primary and make 2/r undefined. A zero semi-major axis makes 1/a undefined and does not describe a valid conic orbit.
Current radius must also be positive, and the gravitational parameter must be positive. The semi-major axis is different: it may be negative because that sign is the conventional representation of a hyperbolic orbit. For some positive semi-major axes, a supplied radius can make 2/r − 1/a negative.
That would imply a negative value for speed squared, showing that the stated point cannot lie on the stated real orbit; the calculator returns an input error rather than an imaginary or misleading value. These checks are valuable when validating imported ephemeris data, reviewing hand calculations, or catching a radius confused with altitude. The calculation assumes a two-body Keplerian model with a point-mass or spherically symmetric primary.
Perturbations from oblateness, atmospheric drag, thrust, radiation pressure, or third bodies are outside its scope and require a propagation model.
What you can do with it
Check speed along an elliptical orbit
Compare expected speeds at periapsis, apoapsis, or an intermediate radius using a known gravitational parameter and semi-major axis.
Evaluate a hyperbolic departure
Use a negative semi-major axis to calculate speed at a selected radius on an escape or flyby trajectory.
Validate simulation or ephemeris output
Independently verify that a reported speed is consistent with the stated two-body orbit and current distance.
FAQ
Which units should I use?
Use any coherent system. If mu is in km^3/s^2 and both distances are in km, speed is in km/s; SI inputs produce m/s.
Is current radius the same as altitude?
No. Current radius is measured from the primary body's center. Add the body's reference radius to altitude when that approximation is appropriate.
Can the semi-major axis be negative?
Yes. A negative semi-major axis is the standard convention for a hyperbolic trajectory. Zero is invalid because the equation divides by it.
Why does the calculator reject some positive radii?
The supplied radius and semi-major axis may make speed squared negative, indicating that the point is not physically compatible with that real conic orbit.
Does the result include velocity direction?
No. Vis-viva gives speed magnitude. Direction requires additional state information such as position, orbital elements, or flight-path angle.
Related tools
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/mech/vis-viva \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"gravitational_parameter":398600.4418,"current_radius":7000,"semi_major_axis":10000}'const res = await fetch("https://api.kit.forhosting.com/mech/vis-viva", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"gravitational_parameter": 398600.4418,
"current_radius": 7000,
"semi_major_axis": 10000
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/mech/vis-viva",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"gravitational_parameter": 398600.4418,
"current_radius": 7000,
"semi_major_axis": 10000
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/mech/vis-viva", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"gravitational_parameter":398600.4418,"current_radius":7000,"semi_major_axis":10000}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"gravitational_parameter":398600.4418,"current_radius":7000,"semi_major_axis":10000}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/mech/vis-viva", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"gravitational_parameter": 398600.4418,
"current_radius": 7000,
"semi_major_axis": 10000
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "mech.vis_viva",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |
Technical questions
What does an API calculation cost?
Each API request costs $0.002. The browser calculator can run the same deterministic calculation locally.