# 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](https://siagasweb.sgb.gov.br) 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

```ts
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).

::warning
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](/format/spec/v2/format-reference#level-sign-convention)).
- **The source is kept.** The page as read is stored in `x-siagas.record`, an extension block every reader preserves ([extensibility](/format/spec/v2/format-reference#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](/format/guides/converting-a-report).

## The steps on their own

The import is three steps, each exported:

```ts
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

- The [example wells](/format/reference/examples) are built on SIAGAS records, with the invented parts marked.
- [Converting a report](/format/guides/converting-a-report) for wells that are not in SIAGAS.