API hidrológica · Sudamérica

Delimitación de Cuencas

Delimita una cuenca a partir de un punto de salida y obtén en una sola llamada el polígono de cuenca, red de drenaje, cauce principal, DEM FABDEM y estadísticos topográficos y geomorfológicos listos para análisis en Python, R o SIG.

POST https://fluviotech.com/api/watersheds/delineate/

Quickstart

Envía latitud y longitud del punto de salida en WGS84 (EPSG:4326).

Python

import requests

url = "https://fluviotech.com/api/watersheds/delineate/"

response = requests.post(
    url,
    json={"lat": -15.2550, "lon": -69.8730},
    timeout=180,
)
response.raise_for_status()

result = response.json()

print(result["terrain_statistics"])
print(result["main_stem_statistics"])

CuencaGeoJSON del área contribuyente.

Red de drenajeRed raster D8 extraída automáticamente.

Cauce principalMain stem extendido hasta la cabecera D8.

DEM FABDEMGeoTIFF recortado y enmascarado a la cuenca.

EstadísticosElevación, relieve, longitud y pendiente.

IntegrableCompatible con Python, R, QGIS y flujos reproducibles.

Solicitud

Campo	Tipo	Descripción
`lat`	float	Latitud del punto de salida en grados decimales, EPSG:4326.
`lon`	float	Longitud del punto de salida en grados decimales, EPSG:4326.

Cobertura actual del servicio: Sudamérica. El punto debe estar dentro del dominio hidrológico disponible.

Respuesta

La respuesta combina geometrías GeoJSON con metadatos y estadísticos derivados del DEM.

Estructura resumida

{
  "catchment": {"type": "FeatureCollection", "features": [...]},
  "river_network": {"type": "FeatureCollection", "features": [...]},
  "main_stem": {"type": "FeatureCollection", "features": [...]},
  "dem": {
    "source": "FABDEM",
    "format": "GeoTIFF",
    "download_url": "/api/watersheds/dem/?lat=...&lon=..."
  },
  "terrain_statistics": {
    "elevation_min_m": 3810.50,
    "elevation_mean_m": 4311.77,
    "elevation_max_m": 5738.62,
    "relief_m": 1928.12
  },
  "main_stem_statistics": {
    "length_km": 312.261,
    "headwater_elevation_m": 5431.18,
    "outlet_elevation_m": 3810.50,
    "elevation_drop_m": 1620.68,
    "mean_slope_m_m": 0.00519,
    "mean_slope_percent": 0.519,
    "mean_slope_m_km": 5.19,
    "longitudinal_profile": [...]
  }
}

Valores mostrados: ejemplo de una ejecución de prueba; dependen de la cuenca consultada.

Descargar el DEM de la cuenca

dem.download_url apunta a un GeoTIFF FABDEM enmascarado a la cuenca. Los píxeles externos se escriben como NoData (-9999).

Python · descarga GeoTIFF

from urllib.parse import urljoin
import requests

base_url = "https://fluviotech.com"
dem_url = urljoin(base_url, result["dem"]["download_url"])

r = requests.get(dem_url, timeout=180)
r.raise_for_status()

with open("watershed_dem.tif", "wb") as f:
    f.write(r.content)

Visualización rápida

Python · rasterio + matplotlib

import rasterio
import matplotlib.pyplot as plt

with rasterio.open("watershed_dem.tif") as src:
    dem = src.read(1, masked=True)
    plt.figure(figsize=(8, 7))
    im = plt.imshow(
        dem,
        extent=[src.bounds.left, src.bounds.right,
                src.bounds.bottom, src.bounds.top]
    )
    plt.colorbar(im, label="Elevación (m)")
    plt.xlabel("Longitud")
    plt.ylabel("Latitud")
    plt.title("DEM de la cuenca - FABDEM")
    plt.show()

Estadísticos disponibles

elevation_min_mElevación mínima dentro de la cuenca.

elevation_mean_mElevación media de los píxeles válidos.

elevation_max_mElevación máxima dentro de la cuenca.

relief_mDiferencia entre elevación máxima y mínima.

length_kmLongitud D8 del cauce principal.

headwater_elevation_mCota FABDEM de la cabecera del main stem.

outlet_elevation_mCota FABDEM próxima al punto de salida ajustado.

mean_slope_percentPendiente media del cauce principal en porcentaje.

mean_slope_m_kmPendiente media expresada en m/km.

longitudinal_profilePerfil longitudinal muestreado, limitado para mantener un JSON compacto.

La pendiente media se calcula como (cota de cabecera − cota de salida) / longitud del cauce principal. Se entrega simultáneamente en m/m, %, y m/km.

Cauce principal y cabecera

El umbral de acumulación se utiliza para identificar la red de drenaje visible y seleccionar la rama principal. Una vez identificada, el cauce principal se extiende aguas arriba siguiendo la topología D8 hasta la fuente más lejana que aporta a esa rama. Esto evita truncar la pendiente media únicamente por el umbral usado para visualizar la red.

Ejemplo en R

R · httr2

library(httr2)

base_url <- "https://fluviotech.com"

resp <- request(paste0(base_url, "/api/watersheds/delineate/")) |>
  req_method("POST") |>
  req_body_json(list(lat = -15.2550, lon = -69.8730)) |>
  req_timeout(180) |>
  req_perform()

result <- resp_body_json(resp)

print(result$terrain_statistics)
print(result$main_stem_statistics$mean_slope_percent)

dem_url <- result$dem$download_url
if (!grepl("^https?://", dem_url)) {
  dem_url <- paste0(base_url, dem_url)
}

dem_resp <- request(dem_url) |>
  req_timeout(180) |>
  req_perform()

writeBin(resp_body_raw(dem_resp), "watershed_dem.tif")

Consideraciones técnicas

El punto de salida se ajusta a la red raster disponible antes de delimitar la cuenca.
Las elevaciones y estadísticas dependen de FABDEM y de su resolución espacial.
La red y el main stem son derivados raster D8; no sustituyen una revisión cartográfica cuando el estudio exige validación de campo o cartografía oficial.
Para cuencas grandes, la descarga del GeoTIFF puede ser considerable y conviene usar un timeout amplio.
El perfil longitudinal se reduce a un máximo de puntos para evitar respuestas JSON innecesariamente pesadas.

Para estudios de diseño o expedientes técnicos, valida el punto de salida, red principal y cotas contra información local disponible antes de adoptar los resultados como definitivos.

Endpoints

Método	Ruta	Uso
POST	`/api/watersheds/delineate/`	Delimitación, geometrías y estadísticos.
GET	`/api/watersheds/dem/?lat=...&lon=...`	Descarga del DEM FABDEM recortado.

Volver a FluvioTech Consultar por la API