'' * Returns a list of the questions, components, and texts in the section via GET * ''/'' (number between 1 and 99) * Returns meta data about the question, the component, or the text * ''/'' (number between 1 and 99) * Returns the texts and settings of the item via GET. * Modifies the item via PATCH. * Creates a new item with the given item ID via POST. * Deletes the item via DELETE. * ''/files'' * Lists all images and media files that were uploaded to the survey project via GET. * ''/dataset'' * Returns the data via GET, according to the //Filter Criteria for Valid Cases// as set in the survey project. * To retrieve selected cases, the GET parameters according to [[:en:results:data-api]] can be used. * ''/dataset.csv'' * Like ''dataset'', but returns the dataset in CSV format for R. * ''/uploads'' * Returns a list of the files uploaded by respondents via GET. * ''%%/%%'' * Returns the file via GET * ''/databank'' * Returns the content of the [[:en:create:databank]] via GET * Allows adding and updating entries via POST ===== Retrieving the Project List =====


https://www.soscisurvey.de/admin/api.php?v1/projects


[
	{
		"id": 104,
		"folder": "alpha",
		"title": "Project Alpha",
		"server": "soscisurvey.de",
		"active": true,
		"accessible": true
	},
	{
		"id": 17,
		"folder": "beta",
		"title": "Project Beta",
		"server": "soscisurvey.de",
		"active": true,
		"accessible": true
	},
	{
		"id": 103,
		"folder": "gamma",
		"title": "Project Gamma",
		"server": "soscisurvey.de",
		"active": true,
		"accessible": true
	}
]

* The ''id'' is the database ID that is required to access the survey project. * The entry ''active'' indicates whether the survey project is still active or has already been archived. * The entry ''accessible'' indicates whether the survey project can be reached via this API URL or whether it is located on another survey server and may have to be addressed via the API URL of that survey server. ===== Retrieving Data ===== The following call would retrieve all cases from the project with the ID 130 whose data was changed after February 20, 2025, 4:32 p.m.


https://www.soscisurvey.de/admin/api.php?v1/projects/130/dataset?changedMin=2025-02-20T16:32:00

For the output of the dataset as JSON, see [[:en:results:data-api]] ===== Downloading Files ===== By means of the API and R, you can also download all files uploaded by the respondents from a survey project. Optionally, use the following R Markdown for this. * In your user account, create a new API token under **API Access** that has read access to `/projects` and `/projects/uploads` (you can omit `/projects` if you already know the project ID) * Copy the "API URL" and enter it in the setup block of the R script. * Copy the "API key" and enter it in the setup block as well. * Depending on whether you enter the (numeric) project ID or not, the list of projects is retrieved and displayed, or the files are downloaded directly. --- title: "Download Uploads" author: "SoSci Survey" date: "`r Sys.Date()`" output: html_document --- ## Preparation * Go to the user account, select **API Access** and create a new token that is allowed to read `/projects` and `/projects/uploads` (you can skip `/projects` if you already know the project's ID) * Copy the "API URL" and paste here the setup script below * Copy the "API key" and paste into the script ```{r setup, include=FALSE} # R setup block knitr::opts_chunk$set(echo = TRUE) # Insert the API URL below api_url <- "INSERT HERE" # Insert the API key below api_key <- "INSERT HERE" # Insert the project's ID below, # eventually to be added after running the "projects" block project_id <- 0 if (!require("pacman")) { install.packages("pacman") library("pacman") } p_load("httr2") ``` ## Projects Now, find the project's ID in this list (skip this code block if you already know the project's ID). ```{r projects, results='asis'} if (project_id < 1) { req <- request(paste(api_url, "/projects", sep="")) |> req_auth_bearer_token(api_key) resp <- req |> req_perform() api_projects <- resp |> resp_body_json() for (api_project in api_projects) { cat(paste(" * ID ", api_project$id, ": ", api_project$title, "\r\n", sep="")) } rm(api_projects, api_project, resp, req) } else { cat("Already set a project ID, skipping project listing retrieval.\r\n") } ``` **Note:** Write the project's ID to `project_id` in the setup block (if not already done). **Note:** Should you see an 401 error, make sure to grant the API key reading access to `/projects`. ## Download Uploads Download the uploads to ''/uploads''. ```{r download, results='asis'} if (project_id < 1) { cat("No project ID set, yet. Stopping processing.\r\n") } else { req <- request(paste(api_url, "/projects/", project_id, "/uploads", sep="")) |> req_auth_bearer_token(api_key) resp <- req |> req_perform() api_uploads <- resp |> resp_body_json() dir.create("uploads", showWarnings = FALSE) for (upload_filename in api_uploads$files) { # Skip download if the file already exists if (file.exists(paste("uploads", upload_filename, sep="/"))) { cat(paste(" * ", upload_filename, " (skipped, already present)\r\n", sep="")) } else { cat(paste(" * ", upload_filename, "\r\n", sep="")) # Download the file and store to /uploads req_file <- request( paste(api_url, "/projects/", project_id, "/uploads/", upload_filename, sep="") ) |> req_auth_bearer_token(api_key) req_file |> req_perform(path = paste("uploads", upload_filename, sep="/")) } } rm(upload_filename, api_uploads, resp, req, req_file) } rm(api_key, api_url, project_id) ``` **Note:** Should you see an 401 error, make sure to grant the API key reading access to `/projects/uploads`.