Elevation profile of a line

# Without a key, leave out the Authorization line (500 credits a day per address).
curl --fail-with-body 'https://api.trailsplits.com/v1/elevation-profile' \
  -H "Authorization: Bearer $TRAILSPLITS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[12.1352,46.5369],[12.133,46.536]]},"points":50}'

{
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "elevation-profile/1"
      ]
    },
    "engine": {
      "type": "object"
    },
    "input": {
      "type": "object",
      "properties": {
        "points": {
          "type": "integer"
        },
        "length_m": {
          "type": "number"
        }
      },
      "required": [
        "points",
        "length_m"
      ]
    },
    "elevation": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "terrain",
            "recorded"
          ]
        },
        "method": {
          "type": "string"
        },
        "ascent_m": {
          "type": "number"
        },
        "descent_m": {
          "type": "number"
        },
        "min_m": {
          "type": "number"
        },
        "max_m": {
          "type": "number"
        }
      },
      "required": [
        "source",
        "method",
        "ascent_m",
        "descent_m"
      ]
    },
    "series": {
      "type": "object",
      "properties": {
        "columns": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "distance_m, elevation_m, grade_pct, lon, lat"
        },
        "heights": {
          "type": "string"
        },
        "parts": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "from_m": {
                "type": "number"
              },
              "to_m": {
                "type": "number"
              },
              "first": {
                "type": "integer"
              },
              "last": {
                "type": "integer"
              }
            },
            "required": [
              "from_m",
              "to_m",
              "first",
              "last"
            ],
            "additionalProperties": true
          }
        },
        "points": {
          "type": "array",
          "items": {
            "type": "array",
            "items": {
              "type": "number",
              "nullable": true
            }
          }
        }
      },
      "required": [
        "columns",
        "parts",
        "points"
      ]
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ]
      }
    }
  },
  "required": [
    "schema",
    "engine",
    "input",
    "elevation",
    "series",
    "unknowns"
  ]
}

Send a line. You get the series a chart draws: distance, height, grade and position at each point. You also get the climb read from that series, by the elevation contract, with its method named.

Route analysis gives the totals; this endpoint gives the curve behind them. Both read heights with the same code, so the same line has the same ascent, descent, extremes, steepest stretches and method in both answers.

Which heights

A line across the antimeridian is sampled the short way round. A terrain sample with no data (over open sea the model has none in places) counts as missing, never as a height.

The rules are route analysis's own:

• Terrain heights. Copernicus DEM GLO-30, sampled every 20 m along the line through the TrailSplits elevation sampler (the Planner's heights). On a line over 120 km the spacing grows, so there are never more than 6,000 samples.
• elevation:
  • auto (the default): the check decides.
  • terrain: always the terrain, unless it does not answer.
  • recorded: the file's heights whenever 90 % of its points carry one.

The series follows the heights used:

• Terrain: the contract's smoothed series, a moving average over ±100 m along the line (route-smoothed-100m). Its rises add up to ascent_m.
• Recorded: the file's heights at its own points, with missing heights filled along the line. ascent_m counts rises of 5 m or more (recorded-hysteresis-5m), so it can be less than the sum of every wobble in the series.

series.heights says which one in words.

Grade at a point is the least-squares slope of the series within 50 m centred on it. Near the ends of a part the window is shortened, and it always holds at least the point and its neighbours. A steady climb reads its grade right up to the end of the line, and a noisy file's wobble averages out.

Parts. Each part of a file (a GPX track segment, one line of a MultiLineString) is a run of its own in series.parts. Distance does not run on across the gap between parts, and no point is drawn across it.

Request

{ "gpx": "<gpx…>" }
{ "geometry": { "type": "LineString", "coordinates": [[lon, lat], …] }, "elevation": "terrain", "points": 500 }

Response

Errors

{ "error": { "code", "message" } }.

Versioning

Additive fields may appear in elevation-profile/1. A change of meaning, or a removed field or column, is elevation-profile/2.

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://trailsplits.com/schemas/elevation-profile-1.request.json",
  "type": "object",
  "additionalProperties": false,
  "oneOf": [{ "required": ["gpx"] }, { "required": ["geometry"] }],
  "properties": {
    "gpx": { "type": "string" },
    "geometry": { "type": "object", "required": ["type"] },
    "elevation": { "enum": ["auto", "recorded", "terrain"] },
    "points": { "type": "integer" },
    "caller": { "type": "string" }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://trailsplits.com/schemas/elevation-profile-1.response.json",
  "type": "object",
  "required": ["schema", "engine", "settings_defaulted", "input", "elevation", "series", "unknowns", "timing"],
  "properties": {
    "schema": { "const": "elevation-profile/1" },
    "settings_defaulted": { "type": "array", "items": { "enum": ["elevation", "points"] } },
    "input": { "type": "object", "required": ["format", "parts", "points", "length_m", "heights_share", "median_spacing_m", "gaps_m"] },
    "elevation": {
      "type": "object",
      "required": ["source", "kind", "method", "ascent_m", "descent_m", "min_m", "max_m", "sparse", "steepest", "terrain", "recorded", "contract"],
      "properties": {
        "source": { "enum": ["terrain", "recorded"] },
        "kind": { "enum": ["estimated", "measured"] },
        "method": { "type": "string" },
        "terrain": { "type": ["object", "null"] },
        "recorded": { "type": "object", "required": ["share", "use", "reason"] }
      }
    },
    "series": {
      "type": "object",
      "required": ["columns", "heights", "grade", "spacing_m", "thinned_from", "parts", "points"],
      "properties": {
        "columns": { "type": "array", "items": { "enum": ["distance_m", "elevation_m", "grade_pct", "lon", "lat"] } },
        "thinned_from": { "type": ["integer", "null"] },
        "parts": { "type": "array", "items": { "type": "object", "required": ["from_m", "to_m", "first", "last"] } },
        "points": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } }
      }
    },
    "unknowns": { "type": "array", "items": { "type": "object", "required": ["code", "message"] } },
    "timing": { "type": "object", "required": ["terrain_ms", "total_ms"] }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://trailsplits.com/schemas/elevation-profile-1.error.json",
  "type": "object",
  "required": ["error"],
  "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }
}