Cliente de la API de ISOCAP

isocap_cliente.py calcula isócronas con la API de ISOCAP desde la línea de órdenes. Puede calcular un punto o un lote de puntos leídos de un CSV, y descarga los resultados de cada cálculo:

• el Shapefile en ZIP o el GeoPackage;
• el GeoJSON en EPSG:4326;
• el CSV de parámetros;
• un resumen.csv con una fila por cálculo.

Solo necesita Python 3.11 o posterior, sin paquetes adicionales. Se descarga en ZIP desde la página Cliente API de ISOCAP (menú «API») y se describe también en el manual de usuario, §10.8.

Token

El token es personal y se crea en la página Tokens de ISOCAP. El cliente lo busca en este orden:

1. la opción --token;
2. la variable de entorno ISOCAP_TOKEN;
3. la clave token del fichero de configuración.

Es preferible usar el fichero o la variable de entorno, porque la opción --token queda en el historial de la consola. El cliente nunca muestra el token. No comparta isocap.toml ni lo suba a ningún repositorio (en el de ISOCAP está en .gitignore).

Configuración

Todas las claves de isocap.toml son opcionales; consulte isocap.toml.ejemplo. Lo que se escriba en la línea de órdenes manda sobre el fichero de configuración.

Algunas aclaraciones: - EPSG y azimut del CSV: epsg y azimut solo se aplican a las filas del CSV que dejan vacías esas columnas. - Pausa entre cálculos: la API admite 60 cálculos por minuto y token. Si se supera el límite, el cliente espera y lo vuelve a intentar. - Verificación del certificado: --no-verificar-tls solo sirve para una instalación local con certificado autofirmado.

CSV de puntos

Cada fila es un cálculo, es decir, un punto con un método. Para calcular varios métodos en el mismo sondeo, repita el sondeo en varias filas.

Formato del fichero: - Codificación: UTF-8, con o sin BOM. En Excel, guárdelo como «CSV UTF-8». - Separador: ;, , o tabulador. El cliente lo detecta en la cabecera. - Números: se admite la coma decimal (0,025) y la notación científica (3,7e-6). Con el separador ,, use el punto decimal. - Comentarios: se ignoran las líneas que empiezan por #.

Los parámetros y sus unidades son:

--metodos lista los parámetros que pide cada método, según el catálogo del servidor. Las celdas de los parámetros que un método no usa se dejan vacías; si tienen valor, se ignoran con un aviso. El sentido del caudal depende del método: - en Jacobs y Bear es el caudal ficticio continuo de 24 h; - en el método de la recarga es el caudal anual medio de explotación.

Consulte el manual de usuario, §7.

Uso

# Métodos y parámetros
python isocap_cliente.py --metodos

# Comprobar un CSV sin calcular nada: no gasta cálculos ni necesita token
python isocap_cliente.py --csv puntos_ejemplo.csv --comprobar

# Lote completo con la configuración de isocap.toml
python isocap_cliente.py --config isocap.toml --csv puntos_ejemplo.csv

# El mismo lote en GeoPackage y en otro directorio (manda sobre isocap.toml)
python isocap_cliente.py --config isocap.toml --csv puntos.csv --formato GEODATABASE --salida lote_2

# Un cálculo
python isocap_cliente.py --config isocap.toml --metodo wyssling --id pozo_3 \
    --lon=-4,4104 --lat 40,7761 --azimut 20 \
    --Q_m3_s 0,003 --K_m_s 3,7e-6 --b_m 93 --i 0,025 --me 0,002 --t_d 50

Una coordenada negativa con coma decimal se escribe con =, por ejemplo --lon=-4,4104; si no, la consola la confunde con una opción. Con punto decimal no hace falta: --lon -4.4104.

Resultados

En el directorio de salida, para cada cálculo: - <id>_<método>.zip o .gpkg; - <id>_<método>.geojson; - <id>_<método>_parametros.csv.

Por ejemplo, san_bartolome_wyssling.zip. Si el mismo id y el mismo método se repiten, se añade el principio del job_id.

resumen.csv (UTF-8 con BOM, separador ;) tiene una fila por cálculo, con estas columnas: - los datos de la fila; - estado (ok o error) y mensaje, con el motivo del error o los avisos; - job_id y los nombres de los ficheros; - las salidas del cálculo: primero las comunes (area_m2, perimeter_m, equivalent_radius_m…) y después las propias de cada método. Están en las mismas unidades y con la misma coma decimal que el CSV de parámetros.

El resumen se reescribe tras cada cálculo, así que un lote interrumpido conserva lo hecho. Los cálculos quedan también en el histórico del usuario en ISOCAP, con el identificador API-<job_id>.

Comportamiento ante errores

• Validación previa: antes de calcular, el cliente valida todas las filas con el catálogo del servidor: método conocido y ningún parámetro que falte.
• Errores en una fila: una fila con errores no detiene el lote. Queda en el resumen con estado=error. Esto vale también para los valores que rechaza el servidor, como una porosidad de 0.
• Token no válido: si el token no vale, el lote se interrumpe en el primer cálculo.
• Errores pasajeros: ante los errores de red y los 429, 502, 503 y 504, el cliente espera y lo vuelve a intentar.
• Código de salida: