如何构建clinicaltrials.gov API查询URL实现多状态筛选

我正尝试从ClinicalTrials.gov公开API获取数据，需要构建正确的请求URL，实现以下需求：

• 获取包含搜索词“EGFR”的临床研究列表
• 同时筛选OverallStatus字段为Recruiting或Active, not recruiting的结果

我已经写好处理响应的R函数（无需修改），但尝试了多种查询字符串都无法实现多值筛选，需要正确的查询语法。

现有处理函数（无需修改） #

library(tidyverse)
library(httr)
library(jsonlite)
library(glue)

get_studies_df <- function(query_url){
  
  # 获取临床研究数据
  res <- httr::GET(query_url)
  
  if(!httr::status_code(res) == 200){
    # 请求失败时返回空数据框
    empty_df <- stats::setNames(data.frame(matrix(ncol = 5, nrow = 0)), c("Rank", "NCTId", "Condition", "BriefTitle", "OverallStatus"))
    return(empty_df)
  }
  
  # 从响应对象中提取数据
  data <- httr::content(res, as="text", encoding = "UTF-8") %>%
    jsonlite::fromJSON()
  
  # 整理临床研究数据框
  studies_df <- data$StudyFieldsResponse$StudyFields %>%
    # 合并多个病症
    dplyr::rowwise() %>%
    mutate(Condition = paste(Condition, collapse = ", ")) %>%
    dplyr::ungroup()
  # 展开列表型列，显示完整文本
  for (i in c(1:ncol(studies_df))){
    studies_df[,i] <- unlist(studies_df[,i])
  }
  
  return(studies_df)
  
}

之前尝试的错误查询 #

# 获取所有含EGFR的研究（可用，但结果过多）
query_url <- "https://ClinicalTrials.gov/api/query/study_fields?expr=EGFR&fields=NCTId,Condition,BriefTitle,OverallStatus&fmt=json"

# 仅获取Recruiting状态的研究（可用）
query_url <- "https://ClinicalTrials.gov/api/query/study_fields?expr=EGFR+AREA[OverallStatus]+Recruiting&fields=NCTId,Condition,BriefTitle,OverallStatus&fmt=json"

# 仅获取Active状态的研究（可用）
query_url <- "https://ClinicalTrials.gov/api/query/study_fields?expr=EGFR+AREA[OverallStatus]+Active&fields=NCTId,Condition,BriefTitle,OverallStatus&fmt=json"

# 尝试获取Recruiting或Active的研究（均失败）
# 仅返回Active状态
query_url <- "https://ClinicalTrials.gov/api/query/study_fields?expr=EGFR+AREA[OverallStatus]+Recruiting+Active&fields=NCTId,Condition,BriefTitle,OverallStatus&fmt=json"
# 返回空结果
query_url <- "https://ClinicalTrials.gov/api/query/study_fields?expr=EGFR+AREA[OverallStatus]+RANGE[Recruiting,Active]&fields=NCTId,Condition,BriefTitle,OverallStatus&fmt=json"
# 仅返回Active状态
query_url <- "https://ClinicalTrials.gov/api/query/study_fields?expr=EGFR+AREA[OverallStatus]+Recruiting+AREA[OverallStatus]+Active&fields=NCTId,Condition,BriefTitle,OverallStatus&fmt=json"
# 返回所有状态的研究
query_url <- "https://ClinicalTrials.gov/api/query/study_fields?expr=EGFR+AREA[OverallStatus]+Recruiting+OR+Active&fields=NCTId,Condition,BriefTitle,OverallStatus&fmt=json"

正确的查询方案 #

直接使用的查询URL #

https://ClinicalTrials.gov/api/query/study_fields?expr=EGFR+AND+(AREA[OverallStatus]+Recruiting+OR+AREA[OverallStatus]+%22Active%2C+not+recruiting%22)&fields=NCTId,Condition,BriefTitle,OverallStatus&fmt=json

语法说明 #

1. 逻辑组合：用AND连接主搜索词（EGFR）和状态筛选条件，确保结果同时满足“含EGFR”和“状态符合要求”
2. OR逻辑包裹：用括号把两个状态的AREA条件包裹，确保OR逻辑仅作用于OverallStatus字段，不会和主搜索词混淆
3. 特殊字符编码：对于包含逗号和空格的状态值Active, not recruiting，需要进行URL编码：
   • 逗号,替换为%2C
   • 空格替换为+
   • 整个值用URL编码后的引号%22包裹（避免歧义）

代码中构建可读性更高的查询 #

可以用glue和url_encode动态构建查询，避免手动编码的麻烦：

# 定义需要筛选的状态值
status_values <- c("Recruiting", "Active, not recruiting")
# 对状态值进行URL编码
encoded_status <- purrr::map_chr(status_values, url_encode)
# 构建查询表达式
expr_str <- glue::glue("EGFR AND (AREA[OverallStatus] {encoded_status[1]} OR AREA[OverallStatus] {encoded_status[2]})")
# 把空格替换为+，适配URL格式
expr_str <- stringr::str_replace_all(expr_str, " ", "+")
# 拼接完整的查询URL
query_url <- glue::glue("https://ClinicalTrials.gov/api/query/study_fields?expr={expr_str}&fields=NCTId,Condition,BriefTitle,OverallStatus&fmt=json")

# 调用函数获取数据
df <- get_studies_df(query_url)

内容的提问来源于stack exchange，提问作者mandmeier