Elevation Profile

{
  "point_count": 111,
    "distance_km": 50.452,
    "elevation_gain_m": 180,
    "elevation_loss_m": 159.4,
    "net_change_m": 20.6,
    "min_elevation_m": 0,
    "max_elevation_m": 104.5,
    "max_grade_percent": 13.2,
    "average_grade_percent": 1.2,
    "steepest_grades": {
      "window_100m": {
        "grade_percent": 13.2,
        "lat": -22.882,
        "lon": -43.074
      },
      "window_500m": {
        "grade_percent": 8.3,
        "lat": -22.882,
        "lon": -43.074
      },
      "window_1km": {
        "grade_percent": 6.5,
        "lat": -22.882,
        "lon": -43.079
      }
    },
    "terrain_difficulty": 19,
    "energy_multiplier": 1.36

}

elevation_gain_m / elevation_loss_m — cumulative positive and negative elevation changes along the route (always positive values). net_change_m is gain minus loss.

max_grade_percent / average_grade_percent — steepest single-segment grade and the mean absolute grade across all segments. Grade is rise-over-run expressed as a percentage.

steepest_grades — the location and grade of the steepest section evaluated over three sliding windows (100 m, 500 m, 1 km). Useful for understanding whether the worst grade is a sharp spike or a sustained climb.

terrain_difficulty — a 0–100 score combining total elevation change, max grade, and route distance. Higher values indicate routes that are harder for vehicles or logistics.

energy_multiplier — estimated energy cost relative to flat terrain. A value of 2.6× means a vehicle consumes roughly 2.6 times the flat-road energy over this route.

include_points: true — when set, each input coordinate is returned with its elevation, cumulative distance from start, and grade to the next point. With format=geojson these become GeoJSON Point features plus a LineString.

API usage cost — billed as 1 usage per 10 coordinates (minimum 2, maximum 51):
1–10 pts = 2  ·  11–20 pts = 3  ·  50 pts = 6  ·  100 pts = 11  ·  500 pts = 51

Point density matters for accuracy — grade analysis is computed between consecutive input points. Sparse points (spaced kilometres apart) produce grades that reflect straight-line terrain rather than road geometry. For meaningful results, aim for points spaced every 100–300 metres along the route. Router APIs such as OSRM or Valhalla return dense road-snapped geometry suitable for this endpoint.

Coordinate precision — use at least 4 decimal places of precision (≈11 m accuracy). Rounding to 3 decimal places (≈111 m) can shift coordinates onto adjacent terrain pixels, producing inflated grade readings — particularly in mountainous areas with steep escarpments such as the Serra do Mar or the Sierra de las Cruces.

Geometry simplification — if you simplify a route linestring before submitting, do so conservatively in hilly or mountainous terrain. Dropping intermediate points on switchbacks means the grade between retained points may reflect raw terrain slope rather than road grade, and reported values like max_grade_percent and steepest_grades will be overstated.

Maximum points — the endpoint accepts up to 500 points per call. For longer routes, split the linestring into segments of 500 points or fewer and call the endpoint once per segment.