welldotdocs
Guides

SIAGAS import

Import a Brazilian well from the SIAGAS groundwater registry, and its RIMAS monitoring series, into a .well file with @welldot/utils/siagas.

SIAGAS is the groundwater information system of the Geological Survey of Brazil (SGB), with records of hundreds of thousands of wells. RIMAS is its groundwater monitoring network. @welldot/utils/siagas reads a well's public SIAGAS page, and for monitoring wells its RIMAS level series and photos, and converts them into a .well file.

Import a well

import { SiagasError, importSiagasWell } from '@welldot/utils/siagas';

try {
  const { json, well, warnings } = await importSiagasWell('3100020782', {
    rimas: 'monthly', // 'none' | 'monthly' (last reading of each month) | 'all'
    media: true, // RIMAS photos and documents as root attachments
  });

  // json: the .well text, ready to save
  // well: the same data as a Well object
  // (the result also has source: { url, rimas_url?, fetched_at })
  for (const w of warnings) console.log(w.message.pt); // also w.message.en
} catch (error) {
  if (error instanceof SiagasError) console.log(error.kind);
  // 'invalid_code' | 'not_found' | 'upstream' | 'parse' | 'conversion'
}

The argument is the SIAGAS point code (the ponto number in the registry's URL).

Unlike the rest of the package, this entry point does network requests (with the global fetch, or one you pass in the options). The SGB pages send no CORS headers, so a browser cannot call them directly. Run the import on a server or in a script.

What the conversion does

The conversion is faithful: nothing is invented.

  • Kept as recorded. Overlapping intervals and values that disagree stay as the registry has them, and each becomes a warning, so you decide what to fix. Only exact duplicate rows are dropped.
  • Zeros interpreted per field. SIAGAS writes 0 for "no data". A lithology layer starting at 0 m is real; a ground elevation of 0 m is not, and is left out.
  • Censored values. Negative concentrations, the registry's way of writing "below the detection limit", become results with qualifier: "<".
  • Flowing wells. "Surgência: S" makes the static level negative, as the format records flowing wells (level sign convention).
  • The source is kept. The page as read is stored in x-siagas.record, an extension block every reader preserves (extensibility).

Warnings are messages in Portuguese and English describing what could not be carried over or needed a decision. Read them before trusting the file, the same way you would review any converted report.

The steps on their own

The import is three steps, each exported:

import { serializeWell } from '@welldot/core';
import {
  parseRimasPage,
  parseSiagasPage,
  siagasToWell,
} from '@welldot/utils/siagas';

const record = parseSiagasPage(html); // the registry page's HTML → a structured record
const rimas = parseRimasPage(rimasHtml); // a RIMAS page → its readings and media
const { well, warnings } = siagasToWell(record, {
  rimas,
  rimasMode: 'monthly',
});
const json = serializeWell(well);

Use them to work from pages you saved earlier, to test with fixtures, or to plug in your own HTTP client.

Related

Logger import

Formatting