Skip to content

Search

Note

The search API is a semi-stable endpoint. We are currently in the process of reviewing which fields we include in free text search. The number of facets/filters may change over time as the ImmPort data model changes to support new types of data. The values to use for the facets are constantly being updated as new controled vocabulary terms are identified for a facet.

Overview

The following endpoints support search for studies or subject using both free text and faceted search. The number of facets that are supported may vary overtime, depending on changes to the data model and the quality of data submitted for the studies and subjects. Each facet that can be used to filter results, is generally backed by a controlled vocabulary table for each facet.

For example to filter by the researchFocus facet, the list of applicable values can be found in the lk_research_table. For details on the API to use for retrieving Lookup(Controlled Vocabulary) informaton refer to the Lookup Tables page.

The API call using just the researchFocus facet would look like

https://www.immport.org/data/query/api/search/study?researchFocus=Infection Response

BASE URL = https://www.immport.org/data/query/api/search

OpenAPI - Swagger Documention

Endpoints

Endpoint Description BASE URL + Endpoint
Study Search Search for Study Metadata study
Study Search Download Download the results of a search for Study Metadata study/download
Subject Search Search for Subject Metadata subject
Subject Search Download Download the results of a search for Subject Metadata subject/download

Query Parameters

Each of the API endpoints mentioned in the table above can have the following list of filter criteria fields passed as parameters to filter the data to meet a specific set of search and filter requirements. One or more of the filter fields can be passed as parameters to the various API endpoints.

If there is an entry in the Reference Table column, this means the values for these filters are limited to a specific set of values. In the ImmPort data model these tables are designated as lookup tables, another common term for these type of tables are controlled vocabulary tables. For details on the API to use for retrieving Lookup(Controlled Vocabulary) informaton refer to the Lookup Tables page.

The values passed to the filter parameters are case sensitive. For the examples below we will be using the **pageSize** parameter to limit the results to 2.
Parameter Description Reference Table Example
term Search Term for free text search /study?term=Covid&pageSize=2
/subject?term=Covid&pageSize=2
fromRecord Number of the Row to Start the Search ?assayMethod=ELISA&pageSize=2&fromRecord=3
pageSize Number or rows or hits to return ?assayMethod=ELISA&pageSize=2
sortField (Study) Field to use for sorting studies. If you specify a sortField you must also specify a sortFieldDirection. study_accession, actual_enrollment, brief_title, condition_or_disease,contract_grant_name, contract_grant_external_id, doi, gender_included, latest_data_release_version_number, latest_data_release_date, min_age, program_name, pubmed_id, research_focus, species, study_pi
sortField (Subject) Field to use for sorting subjects. If you specify a sortField you must also specify a sortFieldDirection study_accession, subject_accession, arm_name, assay_method, biosample_type, clinical_trial, condition_or_disease, ethnicity, gender, has_assessment, has_lab_test, min_age, race, research_focus, species
sortFieldDirection Sort ascending or descending asc, desc
sourceFields (Studies) Specify which fields to return study_accession, actual_enrollment, age_range, analyte_preferred_count, assay_method_count, assessment_panel_count, brief_title, condition_or_disease, contract_grant_external_id, contract_grant_name, doi, gender_included, initial_data_release_date initial_data_release_version_number, lab_test_panel_count, latest_data_release_version_number, latest_data_release_date, min_age, max_age, planned_visit_total_count, program_name, pubmed_id, research_focus, shared_subject_count, species, study_pi ?..&sourceFields=study_accession,research_focus,condition_or_disease
sourceFields (Subject) Specify which fields to return study_accession, subject_accession, arm_name, assay_method,biosample_type, clinical_trial, condition_or_disease, ethnicity,gender, has_assessment, has_lab_test, min_age,race, research_focus, species ?..&sourceFields=study_accession,subject_accession,gender,race
assayMethod Experiment Assay Method lkExpMeasurementTech?format=json /study?assayMethod=ELISA&pageSize=2
/subject?assayMethod=ELISA&pageSize=2
biosampleType Biosample Type lkSampleType?format=json /study?biosampeType=Bone&pageSize=2
/subject?biosampeType=Bone&pageSize=2
clinicalTrial Flag to indicate study is a clinical trial Y or N /study?clinicalTrial=Y&pageSize=2
/subject?clinicalTrial=Y&pageSize=2
conditionOrDisease Condition or Disease lkDisease?format=json /study?conditionOrDisease=COVID-19&pageSize=2
/subject?conditionOrDisease=COVID-19&pageSize=2
ethnicity Ethnicity lkEthnicity?format=json /study?ethnicity=Hispanic or Latino&pageSize=2
/subject?ethnicity=Hispanic or Latino&pageSize=2
gender Gender lkGender?format=json /study?gender=Female&pageSize=2
/subject?gender=Female&pageSize=2
hasAssessment Flag to indicate whether study or subject has assessment data Y or N /study?hasAssessment=Y&pageSize=2
/subject?hasAssessment=Y&pageSize=2
hasLabTest Flag to indicate whether study or subject has lab test data Y or N /study?hasLabTest=Y&pageSize=2
/subject?hasLabTest=Y&pageSize=2
programName Filter using Program Name /study?programName=SeroNet&pageSize=2
/subject?programName=SeroNet&pageSize=2
race Race lkRace?format=json /study?race=Asian&pageSize=2
/subject?race=Asian&pageSize=2
researchFocus Research Focus is a broad categorization of study types lkResearchFocus?format=json /study?researchFocus=Vaccine Response&pageSize=2
/subject?researchFocus=Vaccine Response&pageSize=2
species Species lkSpecies?format=json /study?species=Homo sapiens&pageSize=2
/subject?species=Homo sapiens&pageSize=2
studyAccession Filter by the study accession /study?studyAccession=SDY1,SDY2&pageSize=2
/subject?studyAccession=SDY1,SDY2&pageSize=2
subjectAccession Filter by the subject accession Experimental Endpoint /subject?subjectAccessionAccession=SUB106737,SUB106738&pageSize=2
ageRange Filter by subject ages (Ex. 10-20) /subject?ageRange=10-20i&sortField=min_age&sortFieldDirection=asc&pageSize=2