Package 'eolas'

Description

eolas caches at two levels: session metadata (eolas_info() per dataset, used for routing and attached column glosses) and on-disk bulk files (Parquet/GeoParquet in the library directory, with .eolas-meta.json sidecars). This function clears one or both without contacting the API.

Usage

eolas_cache_clear(
  name = NULL,
  cache_dir = NULL,
  format = NULL,
  files = TRUE,
  meta = TRUE,
  base_url = EOLAS_BASE_URL
)

Arguments

Details

Use eolas_get() or eolas_get_local() with force = TRUE to clear caches and immediately re-fetch in one step.

When name is set and format = NULL, removes on-disk files for all bulk extensions (.parquet, .csv.gz, .geo.parquet) that exist for that dataset. When name = NULL and files = TRUE, sweeps the entire library directory for bulk data files and sidecars.

Value

Invisibly a list with files (character vector of deleted paths) and meta_cleared (integer count of session cache entries removed).

See Also

eolas_get(), eolas_sync_bulk(), eolas_get_local(), eolas_library_status()

Examples

## Not run: 
# Free disk space without re-downloading
eolas_cache_clear("nz_parcels")

# Metadata only (e.g. after a warehouse schema change)
eolas_cache_clear("nz_cpi", files = FALSE)

# Nuclear option -- wipe library files + all session metadata
eolas_cache_clear(name = NULL)

## End(Not run)

Description

Looks up the human-readable gloss for a column name from the metadata attached at fetch time (built server-side from the Iceberg schema).

Usage

eolas_column_label(x, column)

Arguments

Value

Character description, or NULL if unknown / not attached.

Examples

## Not run: 
df <- eolas_get("nz_cpi", limit = 10)
eolas_column_label(df, "value")

## End(Not run)

Description

Wraps GET /v1/bulk/{namespace}/{table} to download a whole Iceberg table as a Parquet, gzipped-CSV, or GeoParquet snapshot – no row caps, no pagination.

Usage

eolas_download_bulk(
  name,
  freshness = "auto",
  format = "parquet",
  path = NULL,
  progress = NULL,
  base_url = EOLAS_BASE_URL,
  ...
)

Arguments

Details

The endpoint requires both namespace and table. These are resolved automatically by calling GET /v1/datasets/{name} first and reading the metadata. The extra round-trip is negligible; monthly snapshots are served from Cloudflare's edge cache in milliseconds.

Value

Invisibly the normalised path when path is set; a raw vector when path = NULL.

Freshness

freshness = "auto" (the default) omits the query parameter so the server redirects to the right level for your plan – Free accounts get the latest monthly snapshot; Pro accounts get the current Iceberg snapshot. Pass "monthly" or "current" to override explicitly.

Formats

"parquet"

Apache Parquet – best for R (via the arrow package), Polars, DuckDB, Spark.

"csv_gz"

Gzipped CSV – readable by read.csv(), readr::read_csv(), Excel.

"geoparquet"

GeoParquet 1.0 – only available on datasets with geometry; read with sfarrow::st_read_parquet() or geopandas.

Error conditions

HTTP 402

Stops with "Bulk upgrade required:" – freshness = "current" requires a Pro plan.

HTTP 403 (licence)

Stops with "Bulk licence restricted:" – dataset is excluded from bulk (e.g. OECD). Use eolas_get() instead.

HTTP 503

Stops with "Bulk not yet available:" – monthly snapshot not yet generated.

See Also

https://docs.eolas.fyi/bulk-downloads/

Examples

## Not run: 
eolas_key("your_key")

# Return raw bytes (e.g. hand to arrow::read_parquet)
raw_bytes <- eolas_download_bulk("nz_cpi")
df <- arrow::read_parquet(raw_bytes)

# Write to a file, get the path back
path <- eolas_download_bulk("nz_cpi", path = "nz_cpi.parquet")
df <- arrow::read_parquet(path)

# Gzipped CSV (readable by read.csv)
eolas_download_bulk("nz_cpi", format = "csv_gz", path = "nz_cpi.csv.gz")
df <- read.csv(gzfile("nz_cpi.csv.gz"))

# Force monthly freshness (reproducibility)
eolas_download_bulk("nz_cpi", freshness = "monthly", path = "nz_cpi.parquet")

# GeoParquet for a geospatial dataset
eolas_download_bulk("territorial_authority_2023",
                    format = "geoparquet",
                    path   = "ta2023.geo.parquet")

# Silence the bar in a script run interactively
eolas_download_bulk("nz_cpi", path = "nz_cpi.parquet", progress = FALSE)

## End(Not run)

Description

The generic workhorse – use eolas_get_statsnz(), eolas_get_oecd() etc. for source-tagged results and a nicer print output.

Usage

eolas_get(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  meta = TRUE,
  envelope = FALSE,
  progress = NULL,
  force = FALSE,
  base_url = EOLAS_BASE_URL,
  ...
)

Arguments

Details

Hits the live ⁠/v1/datasets/{name}/data⁠ endpoint for slices and smaller datasets. Whole-dataset pulls on large or geospatial tables are auto-routed to eolas_get_local() (CDN-backed Parquet/GeoParquet) – so eolas_get("nz_addresses") and eolas_get_linz("nz_addresses") work without hitting the API 413 guard.

Value

A eolas_dataset tibble with date coerced to Date, or an sf object when geometry is present and conversion is enabled. Table and column metadata are attached as attributes (not printed by default).

Examples

## Not run: 
eolas_key("your_key")
df <- eolas_get("nz_cpi", start = "2020-01-01")
library(ggplot2)
ggplot(df, aes(date, value)) + geom_line()

## End(Not run)

Description

Fetch an ACC dataset

Usage

eolas_get_acc(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Description

A named wrapper over eolas_get() for datasets sourced from the Auckland Council open data hub. Covers district plan overlays, notable trees, significant ecological areas, heritage, and stormwater management zones.

Usage

eolas_get_akl_council(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://data-aucklandcouncil.opendata.arcgis.com. Licence: CC-BY 4.0 (Auckland Council).

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_akl_council("akc_notable_trees_overlay")
gdf <- eolas_get_akl_council("akc_significant_ecological_areas_overlay")

## End(Not run)

Description

A named wrapper over eolas_get() for datasets sourced from Auckland Transport (AT). Covers bus stops, bus routes, bridges, and cycle infrastructure.

Usage

eolas_get_akl_transport(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://data-atgis.opendata.arcgis.com. Licence: CC-BY 4.0 (Auckland Transport).

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_akl_transport("akt_bus_stop")
gdf <- eolas_get_akl_transport("akt_cycle_facility_network")

## End(Not run)

Description

A named wrapper over eolas_get() for datasets from Bay of Plenty Regional Council and its territorial authorities. Covers flood extents, liquefaction, coastal hazards, and planning layers.

Usage

eolas_get_bay_of_plenty(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://www.boprc.govt.nz. Licence: CC-BY 4.0.

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_bay_of_plenty("boprc_historic_flood_extents")
gdf <- eolas_get_bay_of_plenty("boprc_liquefaction_level_b")

## End(Not run)

Description

A named wrapper over eolas_get() for datasets from Charities Services (a business unit of the Department of Internal Affairs). Covers registered charities, officers, beneficiary groups, and annual financial returns.

Usage

eolas_get_charities(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://www.charities.govt.nz. Licence: Open Government Licence v3.0.

Value

A eolas_dataset data frame.

Examples

## Not run: 
eolas_key("your_key")
df <- eolas_get_charities("charities_organisations")
df <- eolas_get_charities("charities_annual_returns")

## End(Not run)

Description

A named wrapper over eolas_get() for datasets aggregated via the Co-Lab Waikato open data hub. Covers district plan zones, coastal hazards, heritage, and building footprints across Waikato-region territorial authorities.

Usage

eolas_get_colab_waikato(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://data-waikatolass.opendata.arcgis.com. Licence: CC-BY 4.0 (respective councils).

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_colab_waikato("wmkdc_buildings")
gdf <- eolas_get_colab_waikato("tcdc_dp_coastal_environment")

## End(Not run)

Description

A named wrapper over eolas_get() for datasets sourced from the Department of Conservation (DOC). Covers public conservation land polygons, hut and campsite locations, walking experiences, tracks, marine reserves, and marine mammal sanctuaries.

Usage

eolas_get_doc(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Refreshed weekly from DOC's ArcGIS hub. Operational alert streams (track closures, hazard notices) are wired but currently blocked on an API key issue; they will appear automatically once resolved. Source: https://doc.govt.nz. Licence: CC-BY 4.0 International (Crown / Department of Conservation).

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
huts  <- eolas_get_doc("doc_huts")                        # 1,429 DOC huts (Point)
land  <- eolas_get_doc("doc_public_conservation_land")    # ~11k conservation land polygons
trks  <- eolas_get_doc("doc_tracks")                      # 3,248 DOC tracks (Polyline)

## End(Not run)

Description

A named wrapper over eolas_get() for datasets from Environment Canterbury (ECan) and Canterbury-region councils. Covers liquefaction, earthquake faults, tsunami zones, water allocation, and resource consents.

Usage

eolas_get_ecan_canterbury(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://opendata.canterburymaps.govt.nz. Licence: CC-BY 4.0 (Environment Canterbury / respective councils).

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_ecan_canterbury("ecan_liquefaction_susceptibility_final")
gdf <- eolas_get_ecan_canterbury("ecan_tsunami_evacuation_zones")

## End(Not run)

Description

Fetch an Education Counts dataset

Usage

eolas_get_edcounts(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Description

A named wrapper over eolas_get() for datasets from the Energy Efficiency and Conservation Authority (EECA). Covers NZ energy end-use by sector and fuel type, public and co-funded EV charger locations, quarterly EV penetration metrics by region and territorial authority, and regional industrial process heat demand.

Usage

eolas_get_eeca(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

EV charger streams (eeca_ev_chargers_public, eeca_ev_chargers_cofunded) carry point geometry and refresh quarterly. eeca_energy_end_use is the annual Energy End Use Database (EEUD). eeca_regional_heat_demand is an Aug 2024 snapshot. Source: https://www.eeca.govt.nz/insights/data-tools/. Licence: CC-BY 4.0 NZ (Crown).

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
df  <- eolas_get_eeca("eeca_energy_end_use")         # NZ energy by sector x fuel x end-use x year
gdf <- eolas_get_eeca("eeca_ev_chargers_public")     # public EV charging network (Point geometry)
df  <- eolas_get_eeca("eeca_ev_metrics_district")    # EV penetration by territorial authority
df  <- eolas_get_eeca("eeca_regional_heat_demand")   # industrial process heat by region x sector

## End(Not run)

Description

A named wrapper over eolas_get() for datasets sourced from GeoNet, operated by Earth Sciences New Zealand (formerly GNS Science). Covers recent NZ earthquake activity (MMI>=3), volcanic alert levels for 12 monitored volcanoes, and strong-motion sensor station locations.

Usage

eolas_get_geonet(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

The earthquake catalogue (geonet_quakes_recent) is a rolling window of recent events, not a historical archive. Refreshed every 6 hours. Source: https://www.geonet.org.nz. Licence: CC-BY 3.0 NZ (Earth Sciences New Zealand, formerly GNS Science).

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
df  <- eolas_get_geonet("geonet_quakes_recent")         # rolling ~100 recent MMI>=3 quakes
df  <- eolas_get_geonet("geonet_volcanic_alert_levels") # 12 monitored NZ volcanoes
gdf <- eolas_get_geonet("geonet_strong_motion_sensors") # 25 strong-motion stations

## End(Not run)

Description

A named wrapper over eolas_get() for datasets from Hawke's Bay Regional Council and its territorial authorities. Covers coastal erosion, liquefaction, flood hazards, and district planning layers.

Usage

eolas_get_hawkes_bay(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://www.hbrc.govt.nz. Licence: CC-BY 4.0.

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_hawkes_bay("hbrc_coastal_erosion_likely_66")
gdf <- eolas_get_hawkes_bay("hbrc_chb_hdc_wdc_liquefaction_severity")

## End(Not run)

Description

Fetch an Immigration NZ dataset

Usage

eolas_get_immigration(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Description

Fetch a LINZ series

Usage

eolas_get_linz(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Description

This is the recommended path for large or geospatial datasets in an interactive R session or R Markdown notebook. On the first call it fetches the bulk file from CDN (milliseconds for monthly snapshots) and writes it to ⁠~/.cache/eolas/⁠. On subsequent calls a lightweight HEAD request checks whether the local file is still current; if so the cached copy is read directly – zero network I/O on the data payload.

Usage

eolas_get_local(
  name,
  cache_dir = NULL,
  format = NULL,
  freshness = "auto",
  as_sf = NULL,
  as_arrow = FALSE,
  meta = TRUE,
  progress = NULL,
  force = FALSE,
  base_url = EOLAS_BASE_URL,
  ...
)

Arguments

Details

If you have been calling eolas_get("nz_parcels") on a 3-million-row geospatial dataset and it takes 15+ minutes, use eolas_get_local() instead – it serves a pre-materialised GeoParquet from CDN, not a live Iceberg scan through the row-oriented data endpoint.

Value

A data.frame, sf object, or arrow::Table, depending on the dataset and the as_sf / as_arrow arguments.

Format auto-detection

When format = NULL (the default), eolas_get_local() calls eolas_info(name) and checks the metadata for a geometry_type field. Geo datasets use "geoparquet"; everything else uses "parquet".

GeoParquet and sf

When format = "geoparquet" and the sf package is installed, the returned object is an sf data frame with the CRS read from the GeoParquet metadata (typically OGC:CRS84 / WGS84). If sf is not installed, or as_sf = FALSE, a plain data frame is returned with the WKT geometry preserved as a character column (extracted from the WKB binary by the sfarrow package if available, else left as raw). Install sf with install.packages("sf").

See Also

eolas_sync_bulk(), eolas_library_set(), https://docs.eolas.fyi/bulk-downloads/

Examples

## Not run: 
eolas_key("your_key")

# 3-million-row geospatial dataset -- first call downloads GeoParquet from CDN;
# subsequent calls return in <1 s via sidecar check.
gdf <- eolas_get_local("nz_parcels")

# Non-geo tabular dataset
df <- eolas_get_local("nz_cpi")

# Explicit cache directory (overrides library config -- highest priority)
df <- eolas_get_local("nz_cpi", cache_dir = "/data/eolas-cache")

# Force CSV format
df <- eolas_get_local("nz_cpi", format = "csv_gz")

# Keep plain data.frame even for geo datasets
df <- eolas_get_local("nz_parcels", as_sf = FALSE)

# Arrow table -- zero-copy, no sf allocation; suitable for DuckDB / dplyr
tbl <- eolas_get_local("nz_parcels", as_arrow = TRUE)

## End(Not run)

Description

A named wrapper over eolas_get() for datasets sourced from the Land Resource Information System (LRIS), managed by Manaaki Whenua - Landcare Research NZ. Covers LCDB land-cover vintages (v3.0 through v6), NZLUM land use management, PBC, and the PAN-NZ protected areas layer.

Usage

eolas_get_lris(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

LCDB v3.0-v4.1 are deprecated vintages retained for longitudinal analysis. LCDB v5 is superseded by v6 but still served. pan_nz_2025_draft was marked Draft at the time of ingestion (2026-05-12). Source: https://lris.scinfo.org.nz. Licence: CC-BY 4.0 International (LCDB v5/v6, NZLUM, PBC, PAN-NZ); CC-BY 3.0 NZ (LCDB v3/v4 vintages). Attribution: Manaaki Whenua.

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_lris("lcdb_v6_mainland")   # current NZ land cover
gdf <- eolas_get_lris("nzlum_v03")          # NZ Land Use Management v0.3
gdf <- eolas_get_lris("pan_nz_2025_draft")  # protected areas (Draft, 2025)

## End(Not run)

Description

A named wrapper over eolas_get() for datasets from Horizons Regional Council (Manawatu-Whanganui) and its territorial authorities. Covers airsheds, coastal marine areas, freshwater, and planning layers.

Usage

eolas_get_manawatu_whanganui(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://www.horizons.govt.nz. Licence: CC-BY 4.0.

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_manawatu_whanganui("horizons_coastal_marine_area")
gdf <- eolas_get_manawatu_whanganui("horizons_airshed_taihape")

## End(Not run)

Description

Fetch an MBIE dataset

Usage

eolas_get_mbie(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Description

Fetch an MSD dataset

Usage

eolas_get_msd(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Description

A named wrapper over eolas_get() for datasets from Napier City Council and Whanganui District Council. Covers district plan precincts, heritage buildings and areas, address points, road centrelines, and parcels.

Usage

eolas_get_napier_whanganui(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://www.napier.govt.nz / https://www.whanganui.govt.nz. Licence: CC-BY 4.0.

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_napier_whanganui("napier_heritage_buildings")
gdf <- eolas_get_napier_whanganui("napier_address_points")

## End(Not run)

Description

A named wrapper over eolas_get() for datasets from Northland Regional Council and its territorial authorities (Far North, Whangarei, Kaipara). Covers district plan zones, designations, heritage, and environmental layers.

Usage

eolas_get_northland(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://www.nrc.govt.nz. Licence: CC-BY 4.0.

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_northland("fndc_district_plan_zones")
gdf <- eolas_get_northland("fndc_heritage_areas")

## End(Not run)

Description

Fetch a Waka Kotahi (NZTA) dataset

Usage

eolas_get_nzta(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Description

Fetch an OECD series

Usage

eolas_get_oecd(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Description

A named wrapper over eolas_get() for datasets from Otago Regional Council and its territorial authorities (Dunedin, Queenstown-Lakes, Central Otago, Clutha, Waitaki). Covers land use, floodbanks, groundwater protection, and planning layers.

Usage

eolas_get_otago(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://www.orc.govt.nz. Licence: CC-BY 4.0.

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_otago("orc_otago_irrigated_areas")
gdf <- eolas_get_otago("orc_otago_land_use_2024")

## End(Not run)

Description

A named wrapper over eolas_get() for datasets from PHARMAC (Pharmaceutical Management Agency). Covers the monthly Pharmaceutical Schedule (community- funded medicines and subsidies) and the Hospital Medicines List (HML), including full longitudinal archives from 2006 and 2011 respectively.

Usage

eolas_get_pharmac(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Historical archive datasets (pharmac_schedule_history, pharmac_hml_history) are append-mode; each month's snapshot is tagged with a time_frame column (YYYY-MM format). Source: https://schedule.pharmac.govt.nz/. Licence: CC-BY 3.0 NZ (Crown).

Value

A eolas_dataset data frame.

Examples

## Not run: 
eolas_key("your_key")
df <- eolas_get_pharmac("pharmac_schedule")          # current month's funded medicines
df <- eolas_get_pharmac("pharmac_schedule_history")  # 2006-present subsidy archive
df <- eolas_get_pharmac("pharmac_hospital_medicines_list")  # current HML
df <- eolas_get_pharmac("pharmac_hml_history")       # 2011-present HML archive

## End(Not run)

Description

Fetch an NZ Police / MoJ dataset

Usage

eolas_get_police(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Description

Fetch an RBNZ series

Usage

eolas_get_rbnz(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Description

A named wrapper over eolas_get() for datasets from Environment Southland and its territorial authorities (Southland District, Gore, Invercargill). Covers district plan zones, coastal hazards, heritage, and land use.

Usage

eolas_get_southland(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://www.es.govt.nz. Licence: CC-BY 4.0.

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_southland("sdc_southland_dp_zones")
gdf <- eolas_get_southland("sdc_southland_dp_heritage_items")

## End(Not run)

Description

A named wrapper over eolas_get() that tags the result with the "Stats NZ" source label.

Usage

eolas_get_statsnz(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Value

A eolas_dataset data frame, an sf object when geometry is present and conversion is enabled, or an arrow::Table when as_arrow = TRUE.

Examples

## Not run: 
eolas_key("your_key")
df <- eolas_get_statsnz("bds_enterprises_business_type", start = "2015-01-01")
library(ggplot2)
ggplot(df, aes(date, value)) + geom_line()

## End(Not run)

Description

The server returns source = "Stats NZ" for both SDMX time series and Datafinder geospatial datasets – the eolas_dataset attribute reflects that. This helper exists as a discoverability shortcut, not a separate source.

Usage

eolas_get_statsnz_geo(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Description

A named wrapper over eolas_get() for datasets from Taranaki Regional Council and its territorial authorities (New Plymouth, Stratford, South Taranaki). Covers biodiversity, coastal management, and district planning layers.

Usage

eolas_get_taranaki(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://www.trc.govt.nz. Licence: CC-BY 4.0.

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_taranaki("trc_biodiversity_coastal_mgmt_areas")
gdf <- eolas_get_taranaki("npdc_dp_operative_coastal_flooding")

## End(Not run)

Description

A named wrapper over eolas_get() for datasets from Gisborne District Council, Marlborough District Council, Nelson City Council, and Tasman District Council. Covers coastal hazards, planning zones, and heritage layers.

Usage

eolas_get_top_of_south(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://www.gdc.govt.nz. Licence: CC-BY 4.0.

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_top_of_south("gdc_coastal_environment")
gdf <- eolas_get_top_of_south("gdc_coastal_erosion")

## End(Not run)

Description

Fetch a NZ Treasury series

Usage

eolas_get_treasury(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Description

A named wrapper over eolas_get() for datasets from Greater Wellington Regional Council and its territorial authorities (Wellington, Hutt, Upper Hutt, Porirua, Kapiti Coast). Covers flood and earthquake hazards, district plan zones, and coastal inundation.

Usage

eolas_get_wellington(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://www.gw.govt.nz. Licence: CC-BY 4.0.

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_wellington("wcc_district_plan_zones_2024")
gdf <- eolas_get_wellington("gwrc_flood_1pct_aep")

## End(Not run)

Description

A named wrapper over eolas_get() for datasets from West Coast Regional Council (Te Tai o Poutini) and its territorial authorities (Buller, Grey, Westland). Covers active faults, the Alpine Fault, landslide catalogs, and significant natural areas.

Usage

eolas_get_west_coast(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Details

Source: https://www.ttpp.nz. Licence: CC-BY 4.0.

Value

A eolas_dataset data frame, or an sf object when geometry is present and conversion is enabled.

Examples

## Not run: 
eolas_key("your_key")
gdf <- eolas_get_west_coast("wcrc_active_faults")
gdf <- eolas_get_west_coast("wcrc_alpine_fault_traces")

## End(Not run)

Description

Fetch a WorkSafe NZ dataset

Usage

eolas_get_worksafe(
  name,
  start = NULL,
  end = NULL,
  limit = NULL,
  as_sf = NULL,
  as_arrow = FALSE,
  ...
)

Arguments

Description

Get metadata for a single dataset

Usage

eolas_info(name, base_url = EOLAS_BASE_URL)

Arguments

Value

A one-row tibble with dataset metadata.

Examples

## Not run: 
eolas_key("your_key")
eolas_info("nz_cpi")

## End(Not run)

Description

Calls the eolas Enterprise-only ⁠/v1/integrations/<platform>⁠ endpoint and returns the generated config files. Optionally writes them to disk.

Usage

eolas_integration(
  platform,
  datasets,
  output_dir = NULL,
  force = FALSE,
  base_url = EOLAS_BASE_URL
)

Arguments

Details

Supported platforms:

• "meltano" – meltano.yml using tap-rest-api-msdk, plus README and .env.example. ⁠meltano install && meltano run tap-eolas target-jsonl⁠ and you're loading.

• "fivetran" – Connector Builder YAML for paste-into-dashboard import.

• "azure-data-factory" – linked-service + per-dataset REST datasets + copy pipeline JSON; usable via ⁠az datafactory⁠ CLI or ADF Studio.

This is an Enterprise-plan feature. Non-Enterprise keys receive a 403 from the server; the upgrade pointer flows through verbatim as the error message. See https://eolas.fyi/#pricing.

Value

A list with elements:

• platform – the platform name as echoed by the server.

• files – a named list of filename = content (always populated).

• written – character vector of paths actually written (only present when output_dir is set).

• skipped – character vector of paths skipped because they already existed and force = FALSE.

Examples

## Not run: 
eolas_key("your_enterprise_key")

# In-memory: inspect what the server would generate
result <- eolas_integration("meltano", c("nz_cpi", "nz_gdp"))
names(result$files)
cat(result$files$meltano.yml)

# Write straight to a directory ready for `meltano install`
eolas_integration(
  "meltano",
  c("nz_cpi", "nz_gdp"),
  output_dir = "./my-pipeline"
)

## End(Not run)

Description

Stores the key for the duration of the R session. Alternatively, set the EOLAS_API_KEY environment variable or use eolas_key_save() to persist it to the OS keyring so you never need to call this again.

Usage

eolas_key(key)

Arguments

Value

The key, invisibly.

Examples

## Not run: 
eolas_key("your_key_here")

## End(Not run)

Description

Deletes the entry stored by eolas_key_save(). Does not affect the EOLAS_API_KEY environment variable or the in-session key set by eolas_key().

Usage

eolas_key_clear()

Value

Invisibly NULL.

See Also

eolas_key_save(), eolas_key_status()

Examples

## Not run: 
eolas_key_clear()

## End(Not run)

Description

Stores the key in the OS-native credential store (macOS Keychain, Windows Credential Manager, Linux Secret Service) under service = "eolas", username = "api-key". Once saved, eolas_key() and every ⁠eolas_get_*()⁠ call will find the key automatically – no environment variable or explicit call needed in future sessions.

Usage

eolas_key_save(key = NULL)

Arguments

Details

The same keyring slot is read by the Python eolas-data client, so a key saved from R is immediately available in Python and vice versa.

Requires the keyring package. On Linux, libsecret-1-dev system headers are needed before install.packages("keyring").

Value

Invisibly NULL.

See Also

eolas_key_clear(), eolas_key_status()

Examples

## Not run: 
eolas_key_save()          # interactive prompt
eolas_key_save("vs_...")  # non-interactive

## End(Not run)

Description

Checks all sources in precedence order and reports the first one that has a key, masking all but the first eight characters for safety.

Usage

eolas_key_status()

Details

Precedence:

1. In-session key set by eolas_key()

2. EOLAS_API_KEY environment variable

3. OS keyring (via the keyring package)

4. ⁠~/.eolas/config.json⁠ (as written by the Python CLI ⁠eolas auth set-key⁠)

Value

A character string describing the key source (invisibly). Primarily called for its side-effect of printing a status message.

See Also

eolas_key_save(), eolas_key_clear()

Examples

## Not run: 
eolas_key_status()

## End(Not run)

Description

Removes library_dir from ⁠~/.eolas/config.json⁠. After clearing, eolas_get_local() falls back to ⁠~/.cache/eolas/⁠ (or the EOLAS_LIBRARY env var if set).

Usage

eolas_library_clear()

Value

Invisibly NULL.

Examples

## Not run: 
eolas_library_clear()

## End(Not run)

Description

Writes the chosen path to ⁠~/.eolas/config.json⁠ as library_dir. Future calls to eolas_get_local() will use this directory when no explicit cache_dir argument is passed.

Usage

eolas_library_set(path)

Arguments

Details

The config file is shared with the Python eolas-data client, so a path set from R is immediately honoured in Python and vice versa.

Value

The resolved (absolute) path, invisibly.

Examples

## Not run: 
eolas_library_set("~/eolas-library")
eolas_library_set("/data/eolas")

## End(Not run)

Description

Checks all sources in precedence order and reports which one supplies the library directory:

Usage

eolas_library_status()

Details

1. EOLAS_LIBRARY environment variable

2. library_dir in ⁠~/.eolas/config.json⁠

3. ⁠~/.cache/eolas/⁠ (transient fallback)

Value

A named list with elements source, path, env_var, config_file, and config_value, invisibly. Called primarily for its printed output.

Examples

## Not run: 
eolas_library_status()

## End(Not run)

Description

Returns a tibble (or data frame) with one row per dataset, including name, title, source, namespace, and description.

Usage

eolas_list(source = NULL, base_url = EOLAS_BASE_URL)

Arguments

Value

A tibble.

Examples

## Not run: 
eolas_key("your_key")
eolas_list()
eolas_list("Stats NZ")

## End(Not run)

Description

List all ACC datasets

Usage

eolas_list_acc()

Description

List all Auckland Council datasets available in eolas

Usage

eolas_list_akl_council()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all Auckland Transport datasets available in eolas

Usage

eolas_list_akl_transport()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all Bay of Plenty Councils datasets available in eolas

Usage

eolas_list_bay_of_plenty()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all Charities Services datasets available in eolas

Usage

eolas_list_charities()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all Co-Lab Waikato datasets available in eolas

Usage

eolas_list_colab_waikato()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all DOC datasets available in eolas

Usage

eolas_list_doc()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all ECan / Canterbury datasets available in eolas

Usage

eolas_list_ecan_canterbury()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all Education Counts datasets

Usage

eolas_list_edcounts()

Description

List all EECA datasets available in eolas

Usage

eolas_list_eeca()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all GeoNet datasets available in eolas

Usage

eolas_list_geonet()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all Hawke's Bay Councils datasets available in eolas

Usage

eolas_list_hawkes_bay()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all Immigration NZ datasets

Usage

eolas_list_immigration()

Description

List all LINZ series

Usage

eolas_list_linz()

Description

List all Manaaki Whenua / LRIS datasets

Usage

eolas_list_lris()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all Manawatu-Whanganui Councils datasets available in eolas

Usage

eolas_list_manawatu_whanganui()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all MBIE datasets

Usage

eolas_list_mbie()

Description

List all MSD datasets

Usage

eolas_list_msd()

Description

List all Napier + Whanganui datasets available in eolas

Usage

eolas_list_napier_whanganui()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all Northland Councils datasets available in eolas

Usage

eolas_list_northland()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all Waka Kotahi datasets

Usage

eolas_list_nzta()

Description

List all OECD series

Usage

eolas_list_oecd()

Description

List all Otago Councils datasets available in eolas

Usage

eolas_list_otago()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all PHARMAC datasets available in eolas

Usage

eolas_list_pharmac()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all NZ Police / MoJ datasets

Usage

eolas_list_police()

Description

List all RBNZ series

Usage

eolas_list_rbnz()

Description

List all Southland Councils datasets available in eolas

Usage

eolas_list_southland()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all Stats NZ series

Usage

eolas_list_statsnz()

Value

A data frame (tibble if available) of dataset metadata.

Description

Filters on namespace == "statsnz_geo" rather than the source label, because the source label "Stats NZ" is now shared with the SDMX time-series datasets.

Usage

eolas_list_statsnz_geo()

Description

List all Taranaki Councils datasets available in eolas

Usage

eolas_list_taranaki()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all Gisborne / Top of South Councils datasets available in eolas

Usage

eolas_list_top_of_south()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all NZ Treasury series

Usage

eolas_list_treasury()

Description

List all Wellington Region Councils datasets available in eolas

Usage

eolas_list_wellington()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all West Coast (Te Tai o Poutini) datasets available in eolas

Usage

eolas_list_west_coast()

Value

A data frame (tibble if available) of dataset metadata.

Description

List all WorkSafe NZ datasets

Usage

eolas_list_worksafe()

Description

Faithful port of the Python client's merge_changes. Drops local rows for every pk the feed touched (including deletes), appends the non-delete change rows, applies the current_state_filter, and strips the ⁠_eolas_*⁠ meta columns. The result is the current state for the touched pks merged with the untouched local rows.

Usage

eolas_merge_changes(
  local_df,
  changes_df,
  pk_columns,
  current_state_filter = NULL
)

Arguments

Value

The merged current-state data frame, meta columns stripped, row names reset.

Description

Returns the one-row metadata tibble attached by eolas_get(), eolas_get_local(), and source-specific getters – title, description, licence, refresh cadence, and provenance fields. The full description is available here but is not printed by default; call this accessor when you need the prose.

Usage

eolas_meta(x)

Arguments

Value

A one-row tibble, or NULL when metadata was not attached (e.g. meta = FALSE on the fetch call).

Examples

## Not run: 
df <- eolas_get("nz_cpi", limit = 10)
eolas_meta(df)$description

## End(Not run)

Description

Substring search over the dataset catalog. Common analyst tokens are expanded – e.g. "HLFS" also matches labour-force and unemployment datasets; "OCR" matches official cash rate series.

Usage

eolas_search(query, source = NULL, base_url = EOLAS_BASE_URL)

Arguments

Value

A tibble of matching datasets (same columns as eolas_list()).

Examples

## Not run: 
eolas_key("your_key")
eolas_search("HLFS")
eolas_search("OCR", source = "RBNZ")

## End(Not run)

Description

Reads cdc_serving_tier from the dataset metadata and dispatches:

• "changelog" -> eolas_sync_changes() – incremental /changes feed, pk-merged into the local file (first call downloads a baseline; later calls apply only what changed).

• anything else ("snapshot") -> eolas_sync_bulk() – full-snapshot download, refreshed when the server snapshot changes.

Usage

eolas_sync(
  name,
  path,
  format = "parquet",
  progress = NULL,
  force = FALSE,
  base_url = EOLAS_BASE_URL
)

Arguments

Details

Both paths keep a paste0(path, ".eolas-meta.json") sidecar and return a list with at least status, path, and current_snapshot_id; the changelog path additionally returns sync_mode, previous_seq, current_seq, and ops_applied.

Value

The result list from the dispatched sync (see eolas_sync_changes() / eolas_sync_bulk()).

Examples

## Not run: 
# Same call works whether the dataset is snapshot- or changelog-tier:
eolas_sync("nz_building_outlines", path = "buildings.parquet")

## End(Not run)

Description

Checks whether the locally-cached file is still current by issuing a lightweight HEAD request and reading the X-Snapshot-Version response header. If the snapshot id matches the sidecar, the function returns immediately with status = "unchanged" and no data I/O. Otherwise it downloads the new snapshot, replaces the local file atomically (via a temp file + file.rename()), and updates the sidecar.

Usage

eolas_sync_bulk(
  name,
  path,
  format = "parquet",
  freshness = "auto",
  progress = NULL,
  force = FALSE,
  base_url = EOLAS_BASE_URL,
  ...
)

Arguments

Value

A named list with the same fields as Python's SyncResult:

status

"downloaded", "updated", or "unchanged"

previous_snapshot_id

Snapshot id from the sidecar, or NA if none

current_snapshot_id

Snapshot id from the server

path

Normalised path to the data file

bytes_downloaded

Bytes written (0 when unchanged)

Sidecar

A JSON file ⁠<path>.eolas-meta.json⁠ is written next to the data file. It stores the snapshot id, download timestamp, format, and source URL and is read on the next call to perform the no-op check cheaply.

Atomic replacement

The new file is downloaded to ⁠<path>.eolas-tmp-<rand>⁠ and then renamed over the original with file.rename(). On most POSIX systems this is an atomic inode swap; on Windows it uses MoveFileExW with MOVEFILE_REPLACE_EXISTING. Readers with the file open will see either the old or the new content, never a partial write.

See Also

eolas_download_bulk, https://docs.eolas.fyi/bulk-downloads/

Examples

## Not run: 
eolas_key("your_key")

# First call: full download
r <- eolas_sync_bulk("nz_cpi", path = "nz_cpi.parquet")
r$status           # "downloaded"
r$bytes_downloaded # e.g. 2100000

# Second call (same snapshot): no network I/O on the data file
r <- eolas_sync_bulk("nz_cpi", path = "nz_cpi.parquet")
r$status           # "unchanged"
r$bytes_downloaded # 0

# Poll for updates in a long-running script
repeat {
  r <- eolas_sync_bulk("nz_cpi", path = "nz_cpi.parquet")
  if (r$status != "unchanged") message("Updated to snapshot ", r$current_snapshot_id)
  Sys.sleep(3600)
}

## End(Not run)

Description

The OUT half of CDC. On the first call (cold start) downloads the full baseline via eolas_sync_bulk() and anchors the watermark at the current feed head. On subsequent calls pages only the new changes since the watermark and pk-merges them into the local file (atomic rewrite), applying the dataset's current_state_filter (e.g. is_current = true for SCD2). A 410 (watermark expired) self-heals by re-baselining. Mirrors the Python client's sync_changes.

Usage

eolas_sync_changes(
  name,
  path,
  format = "parquet",
  progress = NULL,
  force = FALSE,
  base_url = EOLAS_BASE_URL
)

Arguments

Value

A list with status, sync_mode = "changelog", previous_seq, current_seq, ops_applied, path, current_snapshot_id.