Line number and km

Rail people locate things by line number and kilometre (“line 1720, km 175.4”). The /v1/linref endpoints convert between that and coordinates. They need an API key with the route scope.

Endpoint	What
`GET /v1/linref/lines`	The calibrated lines of the data version, by line number: name, operator, length, km ranges and calibration quality
`GET /v1/linref/locate?lat=&lon=`	Lines near a point, nearest first: line number, km, side offset, distance
`GET /v1/linref/position?line=&km=`	The coordinates of a km of a line
`GET /v1/linref/segment?line=&from_km=&to_km=`	The line between two km as GeoJSON, with speed, electrification, gauge, line category, gauging and train protection along it

Line numbers are the ref of the OpenStreetMap line relations: the Streckennummer in Germany (1043), 101 04 in Austria (spaces and case don’t matter: 10104 works too), the line number in Switzerland. GET /v1/infra/lines/{line} describes a whole line (or a km range of it) the same way, with the number of parallel tracks; see infrastructure search.

Which lines are there

curl -H "Authorization: Bearer $RAIL_API_KEY" \
  "https://api.routing.gleisklar.de/v1/linref/lines?limit=2"

{
  "results": [
    { "line": "1000", "name": "1000 Lübeck - Puttgarden", "quality": "good", "length_km": 88.9,
      "km_ranges": [ … ] },
    { "line": "1001", … }
  ],
  "next_cursor": "…"
}

(Illustrative values.) Up to 1,000 lines per page (default 100); page through with cursor.

Coordinates → line and km

curl -H "Authorization: Bearer $RAIL_API_KEY" \
  "https://api.routing.gleisklar.de/v1/linref/locate?lat=53.93408&lon=10.30768"

{
  "results": [
    {
      "line": "1043",
      "name": "1043 Neumünster - Bad Oldesloe",
      "km": 103.118,
      "offset_m": -1.9,
      "distance_m": 1.9,
      "lat": 53.934066,
      "lon": 10.307664,
      "accuracy": { "class": "interpolated", "nearest_marker_m": 85.5, "estimated_error_m": 2.1 },
      "calibration": { "quality": "good", "markers_used": 182, "error_m": { "p95": 9, … }, … }
    }
  ],
  "next_cursor": null
}

radius_m (metres, default 100, up to 2,000) limits the search; line restricts it to one line; limit (default 5, at most 20) caps the number of lines.
offset_m is the distance from the line’s reference track, positive to the right in the direction of increasing km. A point on the other track of a double-track line is about ±4 m.
lat/lon in a result are the point projected onto the line.
No line within the radius: 404 (not-in-data).

GET /v1/places/reverse?lat=&lon= gives the same line km for the nearest track, next to the nearest place.

Line and km → coordinates

curl -H "Authorization: Bearer $RAIL_API_KEY" \
  "https://api.routing.gleisklar.de/v1/linref/position?line=1043&km=103.118&offset_m=-1.9"

Returns positions (each with lat, lon, bearing_deg — the direction of increasing km — and accuracy) and the line’s calibration. With offset_m from locate (up to ±500 m), the position is the original point again. Usually there is one position. Where a km jump makes the line count a range twice (an overlap, “Überlänge”), there are two. A km that a jump skips (“Fehllänge”) or that lies beyond the line’s ends returns 404; the problem’s detail lists the line’s km ranges.

Segment with infrastructure

curl -H "Authorization: Bearer $RAIL_API_KEY" \
  "https://api.routing.gleisklar.de/v1/linref/segment?line=1043&from_km=100&to_km=105"

Returns geometry (a GeoJSON LineString from from_km to to_km, either order), from and to (the end points), length_m along the track, and sections of equal infrastructure: max_speed_kmh, electrified, voltage, frequency, energy, gauge, track_class, load, gauging, etcs, train_protection, structure (tunnel or bridge) and rinf_section. Each value says whether it comes from RINF or OSM (*_source). km_jumps_crossed lists the km jumps inside the segment. Both km must lie on the same continuous piece of the line.

How accurate is it?

The km come from calibrating each line’s geometry against the km markers mapped in OpenStreetMap (milestones, signals, level crossings with railway:position). Wrong or rounded markers and other lines’ km are filtered out, and km jumps (Kilometersprung) are detected. Every response includes:

accuracy for the point: class is interpolated (between two markers that agree), extrapolated (beyond the first or last marker), near_km_jump (between the markers either side of a jump whose exact place isn’t mapped) or missing_geometry (the line relation has a gap). It also gives the distance to the nearest marker and an error estimate in metres.
calibration for the line: quality (good, fair, poor), the markers used, the km ranges, every km jump, gaps without markers or geometry, coverage, and error_m (rms, p95, max). That is a leave-one-out test: each marker’s km is predicted from its two neighbours alone.

Converting coordinates to km and back reproduces the point to within 0.5 m, the rounding of the km to metres. How close the km is to the official km depends on the mapped markers: typically a few metres on well-mapped lines (error_m.p95 of 4 to 9 m on the Austrian and German test lines), 10 to 20 m where milestones were placed by hand from aerial imagery, and more on lines with few markers (quality: poor).

Results are planning support, not safety-relevant. Binding positions come from the infrastructure manager.