Getting started

library(Argentum)

What this package talks to

Two OGC standards, and the difference between them decides which function you reach for.

WFS returns features: geometries with attributes, which you can filter, join, measure and reproject. You get an sf object. Use it when you need the data.

WMS returns a picture: the server draws the map with its own cartography and sends you pixels. You get a terra::SpatRaster. Use it when you need a backdrop, an orthophoto, or a layer the publisher only exposes as imagery.

Most organizations publish both. argentum_organizations() tells you which.

Finding an endpoint

orgs <- argentum_organizations()
nrow(orgs)
head(orgs$name)

The catalogue is cached, so this is fast after the first call. To search it:

argentum_search_organizations("catastro")
argentum_search_organizations("buenos aires", service = "wms")

Every reading function accepts either a catalogue name or a bare URL, so you never have to go through the catalogue:

ign <- "https://wms.ign.gob.ar/geoserver/ows"

Seeing what is published

layers <- argentum_layers(ign)
layers[, c("name", "title", "crs")]

The bbox column reports each layer’s extent in WGS84. It is worth reading before you download: it tells you whether the layer covers the whole country or one province, which changes how you should filter.

Reading vector data

The simple case:

provinces <- argentum_read_wfs(ign, "ign:provincia")

The case you will actually use. Three filters, all evaluated on the server, so only the matching features cross the network:

argentum_read_wfs(
  ign, "ign:provincia",
  bbox   = c(-59, -35, -57, -34),
  crs    = 4326,
  filter = "nam = 'Buenos Aires'"
)

bbox also accepts anything sf::st_bbox() understands, which is usually more convenient than typing coordinates:

aoi <- sf::read_sf("my_study_area.gpkg")
argentum_read_wfs(ign, "ign:localidad", bbox = aoi)

Layers too big for one response

Servers cap how many features they will return at once, and many Argentine deployments cap low. argentum_read_wfs() pages automatically: it requests getOption("argentum.page_size") features at a time and stops when the server returns a short page.

If a particular server mishandles startIndex — some older MapServer builds do — turn paging off and cap the request instead:

argentum_read_wfs(ign, "ign:localidad", page_size = Inf, max_features = 1000)

Writing to disk

report <- argentum_download(ign, dir = "data/ign", format = "gpkg")

argentum_download() returns a report rather than stopping at the first failure, because in a bulk download over public infrastructure some layers will fail:

subset(report, status == "error")[, c("layer", "message")]

Prefer "gpkg". Shapefile truncates field names at ten characters, which mangles the descriptive Spanish column names these services tend to use.

When things go wrong

Errors are classed conditions, so you can handle them selectively rather than catching everything:

result <- tryCatch(
  argentum_read_wfs(ign, "ign:provincia"),
  argentum_error_offline = function(e) {
    message("No network; using last night's extract instead.")
    sf::read_sf("cache/provincias.gpkg")
  }
)

The available classes are argentum_error_offline, argentum_error_http, argentum_error_ogc (the server returned a ServiceExceptionReport), argentum_error_capabilities, argentum_error_read, argentum_error_unknown_org, argentum_error_no_endpoint and argentum_error_no_layers.

Caching

The catalogue and every GetCapabilities document are cached in memory for the session and on disk between sessions:

argentum_cache_path()
argentum_cache_clear()
options(argentum.cache_ttl = 60 * 60 * 24 * 7)  # a week

This matters more than it sounds. GetCapabilities on a large GeoServer can take fifteen seconds, and every layer listing and every read needs one.

Using your own catalogue

The bundled catalogue is a snapshot. If you maintain your own list of endpoints — an internal SDI, or a corrected version of ours — point the package at it:

options(argentum.catalog = "endpoints.csv")

The file needs the columns level, jurisdiction, dependency, organization, updated, wms_url, wfs_url, wcs_url and csw_url. A name column is optional; without it, names are built from the organization and whatever else identifies it. Files written for argentum 2.0.0, with category, organization, wms_url and wfs_url, are still accepted and keep their original names.

The bundled snapshot comes from the “Geoservicios_IDERA” spreadsheet, the same source the ArgentinaGeoServices QGIS plugin reads, so both tools see the same endpoints.