Check Terrain Line of Sight
elevation_check_line_of_sightRead-onlyIdempotent
Check whether terrain blocks the straight sightline between an observer and a target, each at a height above the ground, accounting for earth curvature and atmospheric refraction. Returns a verdict of clear, blocked, or indeterminate (when samples along the line have no data), the minimum clearance and the terrain point that limits it, and the first obstruction from the observer when blocked. With frequency_mhz, it also reports first Fresnel zone clearance against the 60% free-space bar. Where Mapzen reports sea-floor depth over open water, clearance is measured to the sea surface; USGS 3DEP values below 0 m (bay floor in some bays, or dry land) count as received unless water_surface_m sets a water level. Models terrain only: buildings and vegetation are not modeled beyond what the elevation source itself captures, and a ridge narrower than the reported sample spacing can be missed. To see the terrain between the points, call elevation_get_profile on the same two points.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | Elevation source: auto (default) uses USGS 3DEP where it has data and Open Topo Data (SRTM, with Mapzen terrain tiles where SRTM has no data) for the rest; usgs_3dep uses 3DEP only; opentopodata uses Open Topo Data only. Case is ignored and spaces or hyphens read as underscores, so USGS-3DEP and open topo data are accepted; 3dep, usgs, and epqs are also aliases for usgs_3dep. | auto |
| target | Yes | Target location as {lat, lon} in decimal degrees (WGS84). | |
| samples | No | Evenly spaced terrain samples along the line, endpoints included (3–250, default 100). Spacing is reported; a ridge narrower than it can be missed. | |
| observer | Yes | Observer location as {lat, lon} in decimal degrees (WGS84). | |
| earth_model | No | Earth model: flat ignores curvature; geometric applies curvature without refraction; optical applies standard visible-light refraction (coefficient 0.13, default); radio applies the standard 4/3-earth radio refraction (coefficient 0.25). | optical |
| frequency_mhz | No | Radio frequency in MHz (30–300,000; 5800 for 5.8 GHz). When set, the result adds first Fresnel zone clearance against the 60% free-space bar; pair it with earth_model radio. | |
| target_height_m | No | Target height above ground, meters (default 0, the ground itself). Set it for a tower, building top, or second antenna. | |
| water_surface_m | No | Water level in meters (-500 to 9,000). When set, each sample's surface, endpoints included, is the higher of its elevation and this level, replacing the default that lifts only Mapzen sea-floor values to 0 m. Set it where the line crosses water: 0 where USGS 3DEP reports a bay floor, or a lake or tide level. | |
| observer_height_m | No | Observer eye or antenna height above ground, meters (default 1.7, standing eye height). |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Guidance on unconfirmed sightlines, thin clearance margins, a clear line short of 60% first Fresnel zone clearance, lines crossing the USGS 3DEP coverage edge, samples over open water or below water_surface_m, and USGS 3DEP values below 0 m. | |
| target | No | The target's end of the sightline; fields as on observer. | |
| fresnel | No | First Fresnel zone clearance; present only when frequency_mhz is set. Zone radius = √(λ·d₁·d₂/D) m, with λ = 299.792458 / frequency_mhz, d₁ and d₂ the distances to each end, and D the line length. | |
| samples | No | Samples along the line, endpoints included. | |
| verdict | No | blocked when terrain reaches the sightline at any sample; clear when every sample between the endpoints has data and lies below it; indeterminate when samples without data leave the line unconfirmed. | |
| observer | No | The observer's end of the sightline, in decimal degrees and meters. Ground elevation is as the dataset reports it; surface is the higher of the ground and water_surface_m when set, otherwise the ground, or 0 where a Mapzen value below 0 marks open water; sightline = surface + height. resolution_m is absent for mapzen. | |
| distance_m | No | Great-circle distance from observer to target, meters. | |
| attribution | No | Sources to credit for the returned values, one line per dataset that answered. | |
| earth_model | No | The earth model applied. | |
| source_mode | No | The source the call used (auto unless the caller chose one). | |
| datasets_used | No | Number of values each dataset answered. | |
| limiting_point | No | The sample between the endpoints with the smallest clearance (first on ties); absent when none of them has data. Units, surface, and resolution_m as on observer, with terrain in place of its ground; bulge is the rise of the curved surface above the straight observer-target chord (0 for flat); clearance = sightline − (surface + bulge), and 0 or below means blocked. | |
| min_clearance_m | No | Smallest clearance over samples between the endpoints, meters (negative means terrain above the sightline). Absent when none of them has data. | |
| missing_samples | No | Samples no queried dataset answered. | |
| min_clearance_ft | No | Smallest clearance in international feet. Absent with min_clearance_m. | |
| first_obstruction | No | The obstructing sample nearest the observer; present only when the verdict is blocked. Fields as on limiting_point. | |
| sample_interval_m | No | Distance between consecutive samples, meters. | |
| samples_with_data | No | Samples with an elevation, endpoints included. | |
| obstructed_samples | No | Samples between the endpoints with clearance 0 or below. | |
| refraction_coefficient | No | Refraction coefficient applied. Absent for the flat model. | |
| effective_earth_radius_m | No | Earth radius divided by (1 − refraction coefficient), meters. Absent for the flat model. |