Skip to contents

Get Stream Segments of a Basin or Upstream of a Point

Source: R/api_get_stream_segments.R
api_get_stream_segments.Rd

This function returns stream segments as an `sf` object with optional filtering by Strahler order. Two modes of operation:

**Basin mode** (default, `upstream = FALSE`): Returns all stream segments *within* a specified basin. The basin can be identified by one of: `basin_id`, `subc_id`, or coordinates (`lon` + `lat`).

**Upstream mode** (`upstream = TRUE`): Returns all stream segments *upstream of* a specified location. Only accepts `subc_id` or coordinates (`lon` + `lat`); `basin_id` is not compatible with upstream mode. All requests are sent as JSON to the API.

Usage

api_get_stream_segments(
  basin_id = NULL,
  subc_id = NULL,
  lon = NULL,
  lat = NULL,
  upstream = FALSE,
  geometry_only = FALSE,
  min_strahler = NULL,
  add_segment_ids = NULL,
  add_upstream_ids = FALSE
)

Arguments

basin_id

Integer. The ID of the basin. Only valid in basin mode (`upstream = FALSE`). One of `basin_id`, `subc_id`, or (`lon` + `lat`) must be provided. Optional. Default: NULL.

subc_id

Integer. A sub-catchment ID from which the basin is inferred (basin mode) or from which to trace upstream (upstream mode). Optional. Default: NULL.

lon

Numeric. Longitude of a point (used together with `lat`). Works in both basin mode and upstream mode. Optional. Default: NULL.

lat

Numeric. Latitude of a point (used together with `lon`). Latitude must be between -90 and 90. Optional. Default: NULL.

upstream

Logical. If `FALSE` (default), returns segments within the basin. If `TRUE`, returns segments upstream of the specified location. Requires `subc_id` or (`lon` + `lat`); `basin_id` is not supported in upstream mode. Default: FALSE.

geometry_only

Logical. If `TRUE`, returns only the geometry of the stream segments without associated attributes. Defaults to `FALSE`.

min_strahler

Integer (optional). The minimum Strahler stream order to include. Streams below this order will be excluded. Defaults to `NULL` (no filtering).

add_segment_ids

Logical (optional). If `TRUE`, segment IDs are added to the output. Only used in basin mode. Defaults to `NULL` (omitted from request).

add_upstream_ids

Logical (optional). If `TRUE`, upstream sub-catchment IDs are added to the output. Only used in upstream mode. Defaults to `FALSE`.

Value

An `sf` object representing the stream segments. Geometry type: LINESTRING.

Details

Sends a request to the GeoFRESH API to retrieve stream segments belonging to a given basin, or all upstream segments of a specific location.

See also

Other ocgapi: api_get_basin_polygon(), api_get_ids(), api_get_snapped_points(), api_get_snapped_points_cascade(), api_get_upstream_catchment()

Examples

if (FALSE) { # \dontrun{
# === BASIN MODE (upstream = FALSE) ===

# Using basin_id
segm_sf <- api_get_stream_segments(
  basin_id = 1288419,
  geometry_only = FALSE,
  min_strahler = 4,
  add_segment_ids = TRUE
)

# Using subc_id
segm_sf <- api_get_stream_segments(
  subc_id = 506586041,
  geometry_only = TRUE
)

# Using lon/lat
segm_sf <- api_get_stream_segments(
  lon = 8.278198242187502,
  lat = 53.54910661890981,
  geometry_only = TRUE
)

# === UPSTREAM MODE (upstream = TRUE) ===

# Using subc_id to get upstream segments
upstream_sf <- api_get_stream_segments(
  subc_id = 506586041,
  upstream = TRUE,
  geometry_only = FALSE,
  min_strahler = 1
)

# Using lon/lat to get upstream segments (Sarantaporos outlet)
upstream_sf <- api_get_stream_segments(
  lon = 20.538704,
  lat = 40.113735,
  upstream = TRUE,
  geometry_only = FALSE
)

# Visualize with leaflet
library(leaflet)
leaflet(upstream_sf) %>%
  addProviderTiles("CartoDB.Positron") %>%
  addPolylines(color = "blue")
} # }