Terrain profile API — elevation along a line

`GET /v1/profile`

Terrain elevation profile along the great circle between two points — useful for drawing the terrain between A and B. Density is controlled by stepM or samples (not both); the number of returned points is capped at 512. Distance must be between 1 m and 50 km. Billed as 2 + ceil((N−2)/10) for N returned samples: the first and last point at the normal 1 unit each, then 1 unit per 10 interior samples (rounded up). A two-point profile costs 2; a 100-sample profile costs 12. Sampling finer than the terrain resolution adds no real detail (see the tip under Request).

Request

Field	Type	Required	Default	Description
`fromLat`	float	yes	—	Start latitude, −90..90.
`fromLng`	float	yes	—	Start longitude, −180..180.
`toLat`	float	yes	—	End latitude, −90..90.
`toLng`	float	yes	—	End longitude, −180..180.
`stepM`	float	no	auto	Metres between points. Mutually exclusive with `samples`.
`samples`	int	no	auto	Number of points, 2..512. Mutually exclusive with `stepM`.

Choosing stepM. The source raster (Copernicus GLO-30) has a ground sample distance of 30 m, echoed back as resolution_m. A stepM below that returns interpolated points, not new information — it costs credits without adding detail. Use stepM ≥ resolution_m unless you specifically need evenly-spaced output at a finer step for rendering.

Examples

curl -H "X-API-Key: gi_live_..." \
  "https://geoinsight.dev/v1/profile?fromLat=53.3310&fromLng=14.2510&toLat=53.3520&toLng=14.2980&stepM=50"

import requests

r = requests.get(
"https://geoinsight.dev/v1/profile",
params={
    "fromLat": 53.3310, "fromLng": 14.2510,
    "toLat": 53.3520, "toLng": 14.2980, "stepM": 50,
},
headers={"X-API-Key": "gi_live_..."},
)
print(r.json()["points"])

const res = await fetch(
  "https://geoinsight.dev/v1/profile?fromLat=53.3310&fromLng=14.2510&toLat=53.3520&toLng=14.2980&stepM=50",
  { headers: { "X-API-Key": "gi_live_..." } },
);
console.log((await res.json()).points);

Response

{
  "distance_m": 4213.7,
  "step_m": 31.2,
  "samples": 136,
  "points": [{ "lat": 53.331, "lng": 14.251, "d_m": 0, "elevation": 42.1 }],
  "min_point": { "lat": 53.352, "lng": 14.238, "d_m": 2140.0, "elevation": 12.4 },
  "max_point": { "lat": 53.361, "lng": 14.231, "d_m": 3018.0, "elevation": 318.9 },
  "dataset": "copernicus-glo-30",
  "resolution_m": 30
}

Field	Type	Unit	Description
`distance_m`	number	m	Great-circle distance between the two endpoints. Independent of sampling density.
`step_m`	number	m	Spacing between consecutive samples, equal to distance_m / (samples − 1).
`samples`	integer	count	Number of returned points, capped at 512. Equals the length of points.
`points`	array	—	Samples ordered from the start point to the end point. The first and last entries are exactly the requested endpoints.
`points[].lat`	number	deg	Latitude of this sample along the great circle.
`points[].lng`	number	deg	Longitude of this sample.
`points[].d_m`	number	m	Distance from the start point. Use this as the x axis when plotting the profile; it runs 0 to distance_m.
`points[].elevation`	number	m a.s.l.	Terrain height at this sample — the y axis of the profile. null where the DEM has no data.
`min_point`	object	—	The full sample (same shape as a points[] entry) with the lowest elevation along the profile — so you know where the low point is, not just how low. Use min_point.elevation for the y-axis floor. null when every sample is outside coverage; ties go to the point nearest the start.
`max_point`	object	—	The full sample with the highest elevation. Pair min_point/max_point for the y-axis range and to mark the extremes on a chart. null when every sample is outside coverage.
`dataset`	string	—	Source dataset identifier.
`resolution_m`	integer	m	Ground sample distance of the source raster. Requesting step_m far below this yields interpolated points, not extra real detail.