Get data from Geosphere Austria's Open Data Hub

Constructs a URL and fetches data from the Geosphere API's main resource endpoint based on the provided parameters. The function allows fetching data as a file path (default), directly into an R object (data frame), or as the raw HTTP response.

Note: This function retrieves data from the primary resource path (e.g., /v1/timeseries/historical/{resource_id}). To retrieve metadata (usually found at /metadata appended to the resource path), you would need to construct the URL manually and use a tool like httr::GET.

See the Geosphere API documentation for details on available endpoints and parameters:

• Getting Started

• Resources

• Datasets Overview

Example endpoint: SPARTACUS Monthly Example metadata URL: SPARTACUS Monthly Metadata

Usage

geosphere_get_data(
  resource_id,
  parameters = NULL,
  start = NULL,
  end = NULL,
  station_ids = NULL,
  output_format = "csv",
  ...,
  api_url = "https://dataset.api.hub.geosphere.at",
  version = "v1",
  type = "timeseries",
  mode = "historical",
  return_format = c("file", "dataframe", "raw"),
  output_file = NULL,
  verbose = FALSE,
  timeout_seconds = 120
)

Arguments

resource_id

Required. The specific dataset or resource ID (e.g., "klima-v2-1m"). Cannot be NULL or empty.

parameters

Character vector or comma-separated string of parameter IDs to retrieve (e.g., c("tl", "tx"), "tl,tx"). Check API metadata for available parameters.

start

Start date/time string (ISO 8601 format preferred, e.g., "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS").

end

End date/time string (ISO 8601 format preferred).

station_ids

Character vector or comma-separated string of station IDs (e.g., c("5925", "11035"), "5925,11035"). Check API metadata for available stations.

output_format

The desired data format from the API (e.g., "csv", "json", "geojson"). Defaults to "csv". Passed as a query parameter.

...

Additional query parameters specific to the API endpoint. Values will be automatically URL-encoded. Use this for less common parameters not covered by explicit arguments.

api_url

Base URL for the Geosphere API.

version

API version string.

type

Data type (e.g., "timeseries", "station", "grid").

mode

Data mode (e.g., "historical", "current", "forecast").

return_format

Character string specifying the desired return type for the R function:

• "file": (Default) Downloads the data to a temporary file (or output_file if specified) and returns the file path.

• "dataframe": Attempts to parse the response content (CSV or JSON) directly into a data frame or list. Requires readr and/or jsonlite packages.

• "raw": Returns the raw httr response object.

output_file

Path where the downloaded data should be saved only when return_format = "file". If NULL (default), a temporary file is used.

verbose

Logical. If TRUE, prints the constructed URL and shows download progress.

timeout_seconds

Request timeout in seconds. Passed to httr::GET.

Value

Depends on return_format:

• "file": The path to the downloaded file.

• "dataframe": A data frame (for CSV) or list/data frame (for JSON), parsed from the response. Requires readr or jsonlite.

• "raw": The raw httr response object.

Examples

if (FALSE) { # \dontrun{
# Ensure necessary packages are installed for 'dataframe' return format
# install.packages(c("readr", "jsonlite"))

# Example 1: Get monthly climate data for a station, save to temp file (default)
temp_csv_path = geosphere_get_data(
    resource_id = "klima-v2-1m",
    parameters = "tl_mittel",
    start = "2023-01-01",
    end = "2023-12-31",
    station_ids = "5925",
    output_format = "csv", # API format is CSV
    type = "station"
    # return_format defaults to "file"
)
print(temp_csv_path)
# data = readr::read_csv(temp_csv_path) # Optionally read the data

# Example 2: Get hourly data and return directly as a data frame
start_time = "2024-04-06T05:00:00"
end_time = "2024-04-06T17:00:00"
try({ # Wrap in try in case readr is not installed or parsing fails
hourly_data = geosphere_get_data(
    resource_id = "klima-v2-1h",
    parameters = "tl",
    start = start_time,
    end = end_time,
    station_ids = 5925, # Numeric ID works too, converted to character
    output_format = "csv", # API format
    type = "station",
    return_format = "dataframe", # Request data frame directly
    verbose = TRUE
)
print(head(hourly_data))
}, silent = TRUE)

# Example 3: Using ... for a less common parameter (e.g., spatial filter)
# Hypothetical example - check API docs for actual parameters
grid_data_path = geosphere_get_data(
    resource_id = "spartacus-v2-1d-1km",
    parameters = "t_2m",
    start = "2023-05-01",
    end = "2023-05-01",
    bbox = "10,47,11,48", # Passed via ...
    type = "grid",
    output_format = "netcdf" # Assuming API supports this
)
print(grid_data_path)

# Example 4: Demonstrating the resource_id check (will cause an error)
# try(geosphere_get_data())
# try(geosphere_get_data(resource_id = NULL))
# try(geosphere_get_data(resource_id = "   "))

# --- How to get METADATA manually ---
# You need to construct the specific metadata URL and use httr directly
metadata_url <- "https://dataset.api.hub.geosphere.at/v1/station/historical/klima-v2-1h/metadata"
response <- httr::GET(metadata_url)
httr::stop_for_status(response) # Check for errors
if (requireNamespace("jsonlite", quietly = TRUE)) {
  metadata_list <- jsonlite::fromJSON(httr::content(response, as = "text", encoding = "UTF-8"))
  print(names(metadata_list))
  print(head(metadata_list$parameters))
} else {
   print("Install jsonlite to parse the metadata JSON")
}
# ---
} # }