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
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.
| 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 |