ForHosting KIT · Developer Utilities

Three-dimensional distance

This three-dimensional distance calculator combines a measured horizontal ground distance with the elevation difference between two points.

● BetaFree · in your browser

Run — free How it works & API

Use it from WebAPIEmailTelegramApp soon

It treats those measurements as the perpendicular legs of a right triangle and returns the direct sloping distance between the points. Use the same length unit for both inputs—metres, feet, kilometres, or another unit—and the answer remains in that unit. The calculation is deterministic, requires no coordinates or map projection, and clearly rejects missing, non-finite, or negative ground-distance values.

Turn a plan distance and height change into a sloping distance

A map, site plan, or field measurement often gives the horizontal separation between two locations, while a level, contour map, or elevation model gives their vertical difference. Those two values describe perpendicular components of one straight segment in three dimensions. The calculator applies the Pythagorean theorem: square the horizontal distance, square the elevation difference, add the squares, and take the square root. For example, a horizontal distance of 120 metres and an elevation difference of 50 metres produce a direct distance of 130 metres. The sign of the elevation difference does not change the length, because squaring makes an ascent and an equal descent contribute identically. Keeping the signed input in the response is still useful because it records whether the second point is above or below the first. This capability is intended for the common situation where horizontal ground distance is already known. It does not infer that distance from latitude and longitude, and it does not model a path that bends with terrain. The returned value is the straight-line, point-to-point slope distance represented by the two perpendicular measurements.

Choose consistent inputs and interpret the result correctly

Enter horizontal_distance as a non-negative finite number. Enter elevation_difference as the elevation of the second point minus the elevation of the first, so positive means the second point is higher and negative means it is lower. Both numbers must use the same unit. If the horizontal measurement is in metres and the elevation difference is in feet, the formula will still run but the result will have no physical meaning; convert one measurement before calling the calculator. No separate unit field is needed because the Pythagorean relationship is unit-independent. A result based on metres is in metres, and a result based on feet is in feet. When the elevation difference is zero, the three-dimensional distance equals the horizontal distance. When the horizontal distance is zero, the result is the absolute elevation difference. The direct distance can never be smaller than either component. The response echoes the normalized inputs, provides distance_3d, and includes the formula label so an application can explain the calculation. API requests cost $0.002 per successful item, while invalid inputs are rejected rather than converted into misleading zeroes or non-numeric JSON values.

Understand the geometric assumptions and practical limits

The calculation assumes that horizontal distance and elevation difference form perpendicular legs in a local Cartesian frame. That is an excellent approximation for construction layouts, short survey lines, hiking segments, cable runs, ramps, and many engineering estimates where a plan distance is paired with a height change. It is not a substitute for a geodesic calculation over long distances on Earth, because curvature and the chosen map projection can affect the horizontal component. It also does not calculate the distance travelled along an uneven trail or across a changing terrain surface; many rises, dips, and turns can make an actual route longer than the single straight segment. Measurement quality matters as much as the formula. A rounded contour elevation or approximate map scale can limit the accuracy of the result even though the arithmetic is exact for the submitted values. The implementation uses a numerically stable hypotenuse operation instead of directly multiplying huge numbers, then verifies that the result remains finite. It performs no network requests, stores no measurements, uses no randomness, and produces the same JSON for the same valid input in both the browser tool and API execution.

What you can do with it

Survey slope checks

Combine a measured horizontal survey line with the elevation change to obtain its direct slope distance.

Cable and pipe estimates

Estimate the straight run between endpoints separated both horizontally and vertically before adding routing allowances.

Trail segment analysis

Compare plan distance with point-to-point 3D distance for a segment whose start and end elevations are known.

FAQ

What formula is used?

The result is the square root of horizontal distance squared plus elevation difference squared.

Which units can I use?

Any length unit works, provided both inputs use the same unit. The result uses that same unit.

Can elevation difference be negative?

Yes. A negative value means the second point is lower; its magnitude contributes to distance in the same way as a positive value.

Is this the distance along the terrain?

No. It is the straight-line distance between two points, not the length of an uneven or winding surface path.

Can I use latitude and longitude?

Not directly. First calculate an appropriate horizontal ground distance, then combine it with the elevation difference here.

What does an API calculation cost?

Each successful API item costs $0.002; the browser calculator is free.

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

POSThttps://api.kit.forhosting.com/geo/distance-3d

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/geo/distance-3d \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"horizontal_distance":120,"elevation_difference":50}'

const res = await fetch("https://api.kit.forhosting.com/geo/distance-3d", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "horizontal_distance": 120,
    "elevation_difference": 50
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/geo/distance-3d",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "horizontal_distance": 120,
    "elevation_difference": 50
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/geo/distance-3d", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"horizontal_distance":120,"elevation_difference":50}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"horizontal_distance":120,"elevation_difference":50}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/geo/distance-3d", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

Example request

{
  "horizontal_distance": 120,
  "elevation_difference": 50
}

Example response

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "geo.distance_3d",
  "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

Per request$0.002

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.

Read the full KIT documentation →