Overview

The Data Query API provides programmatic access to the ImmPort Shared Data. This API works as a query tool to access ImmPort descriptive data (metadata) and interpreted results for assays such as ELISA, ELISPOT, MBAA (Luminex), HAI, Neutralizing Antibody Titers, HLA and KIR typing, QPCR, flow and mass cytometry based on various input filter parameters. The API returns a JSON output by default. A tab separated output can also be returned if format=tsv is passed as a parameter to the specified endpoint. The HTTP method supported by this API is GET for this version of this API.

Tools for communicating with the ImmPort Data Query API

Many third-party tools can be used for communicating with the API and for visualizing API calls.

Examples of tools for communicating with the API:

Tool Type
Curl Command line tool
HTTPie Command line tool
Postman REST Client App for Google Chrome and OS X
DHC REST Client Google Chrome extension
Google Chrome Google Chrome web browser

API Endpoints

Getting data from the Data Query API is accomplished by making calls to the API endpoints.

The HTTP URL that corresponds to the Data Query API endpoint is https://api.immport.org/data/query/result/<endpoint>, where <endpoint> is the name of the endpoint such as elisa.

Each Data Query API endpoint represents a specific API functionality and returns metadata and results, as summarized in the following table:

Endpoint Description HTTP URL
elisa Enzyme-Linked ImmunoSorbant Assay https://api.immport.org/data/query/result/elisa
elispot Enzyme-linked ImmunoSPOT https://api.immport.org/data/query/result/elispot
fcsAnalyzed flow and mass cytometry results https://api.immport.org/data/query/result/fcsAnalyzed
hai Hemagglutination Inhibition https://api.immport.org/data/query/result/hai
hlaTyping Human Leukocyte Antigen typing https://api.immport.org/data/query/result/hlaTyping
kirTyping Killer cell immunoglobulin-like receptors typing https://api.immport.org/data/query/result/kirTyping
mbaa Multiplex Bead Array Assay (Luminex) https://api.immport.org/data/query/result/mbaa
neutAbTiter Neutralizing Antibody Titer Assay https://api.immport.org/data/query/result/neutAbTiter
pcr Quantitative Polymerase Chain Reaction https://api.immport.org/data/query/result/pcr
filePath Path to result files https://api.immport.org/data/query/result/filePath

Sample Request with Authentication

Authentication

All requests to the Data Query API require authentication. The Data Query API uses tokens for authentication.

Users can obtain tokens by posting to the ImmPort Authentication URL https://auth.immport.org/auth/token with a username and password.

This can be done by executing the following curl command:


curl -X POST https://auth.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD"

response from the above curl command:
{
  "status" : 200,
  "token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXV............"
}

The token returned is a JWT token. (You can go to the JWT token URL and enter the token got from the above call. This will give the information that the token contains. The token has information about the username, roles, permissions for the user.

The token must be used to initiate a API request within 60 secs. After 60 secs the token will be invalid and the user will need to get a new token. But once the GET call is initiated then the token will be valid throughout the entire api request call and does not become invalid until the response is returned.

Using the Authentication token

All API requests require authentication. They must include the authentication token as an Authorization: bearer in the custom HTTP header.

In the following example, an authentication token is saved as an environment variable (token) and passed to the HTTP header in the curl command to get back elisa results data.

The following is an example of a request to the elisa endpoint with a single parameter.


#!/bin/bash

export token=`curl -X POST https://auth.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD" 2>&1  | fgrep '"token"' | sed -e 's/^.*"token" : "//;s/".*$//'`

curl -k -H "Authorization: bearer $token" "https://api.immport.org/data/query/result/elisa?studyAccession=SDY2,SDY4"

[ {
  "resultId" : 89390,
  "ageEvent" : "Age at enrollment",
  "ageEventSpecify" : null,
  "ageUnit" : "Years",
  "ancestralPopulation" : null,
  "analytePreferred" : null,
  "analyteReported" : "VZVQual",
  "armAccession" : "ARM235",
  "armName" : "Healthy controls",
  "biosampleAccession" : "BS476749",
  "biosampleType" : "Other",
  "biosampleSubtype" : null,
  "clinical" : "Y",
  "comments" : "negative qualitative result",
  "ethnicity" : "Not Hispanic or Latino",
  "experimentAccession" : "EXP8311",
  "expsampleAccession" : "ES474813",
  "gender" : "Male",
  "maxSubjectAge" : 1.00,
  "measurementTechnique" : "ELISA",
  "minSubjectAge" : 1.00,
  "plannedVisitAccession" : "PV1518",
  "race" : "White",
  "raceSpecify" : null,
  "repositoryAccession" : null,
  "repositoryName" : null,
  "species" : "Homo sapiens",
  "strain" : null,
  "studyAccession" : "SDY2",
  "studyTitle" : "Immune Response to Varicella Vaccination in Subjects with Atopic Dermatitis Compared to Nonatopic Controls",
  "studyTimeCollected" : 1.00,
  "studyTimeCollectedUnit" : "Days",
  "subjectAccession" : "SUB106751",
  "subjectPhenotype" : "non atopic dermititis",
  "unitPreferred" : null,
  "unitReported" : "-1: neg 1: pos",
  "valuePreferred" : -1.0,
  "valueReported" : "-1",
  "treatmentAccession" : null,
  "studyTimeT0EventSpecify" : null,
  "studyTimeT0Event" : "Not Specified"
}, {
  "resultId" : 89391,
  "ageEvent" : "Age at enrollment",
  "ageEventSpecify" : null,
  "ageUnit" : "Years",
  "ancestralPopulation" : null,
  "analytePreferred" : null,
  "analyteReported" : "VZVQual",
  "armAccession" : "ARM235",
  "armName" : "Healthy controls",
  "biosampleAccession" : "BS476750",
  "biosampleType" : "Other",
  "biosampleSubtype" : null,
  "clinical" : "Y",
  "comments" : "negative qualitative result",
  "ethnicity" : "Not Hispanic or Latino",
  "experimentAccession" : "EXP8311",
  "expsampleAccession" : "ES474814",
  "gender" : "Female",
  "maxSubjectAge" : 1.00,
  "measurementTechnique" : "ELISA",
  "minSubjectAge" : 1.00,
  "plannedVisitAccession" : "PV1518",
  "race" : "White",
  "raceSpecify" : null,
  "repositoryAccession" : null,
  "repositoryName" : null,
  "species" : "Homo sapiens",
  "strain" : null,
  "studyAccession" : "SDY2",
  "studyTitle" : "Immune Response to Varicella Vaccination in Subjects with Atopic Dermatitis Compared to Nonatopic Controls",
  "studyTimeCollected" : 1.00,
  "studyTimeCollectedUnit" : "Days",
  "subjectAccession" : "SUB106784",
  "subjectPhenotype" : "non atopic dermititis",
  "unitPreferred" : null,
  "unitReported" : "-1: neg 1: pos",
  "valuePreferred" : -1.0,
  "valueReported" : "-1",
  "treatmentAccession" : null,
  "studyTimeT0EventSpecify" : null,
  "studyTimeT0Event" : "Not Specified"
},........
The first line is a POST to the authentication URL https://auth.immport.org/auth/token with the username and password to get an authentication token. The fgrep command is used search the response for a token and then assign the value of the token to an environment variable named "token".

The second line is a GET on the URL https://api.immport.org/data/query/result/elisa with the filter parameter studyAccession=SDY2,SDY4. The authentication token ("token") is passed in the HTTP header as shown.

The response will return ELISA result data that belongs to study accessions SDY2 and SDY4 (Check the Response tab above). The default format of the response is JSON. The response will be an array of the specific result type or file path data. The filter conditions are always combined using the AND operator.

The above shell script or any code starting with #!/bin/bash can be copied to a .sh file (e.g. elisadata.sh )and executed at the command prompt of a terminal and the output can be directed to a file. (Please replace the REPLACE_WITH_USERNAME with your username and REPLACE_WITH_PASSWORD with your password.)


./elisadata.sh > elisaresult.txt

Filter Criteria

Each of the API endpoints mentioned above can have the following list of filter criteria fields passed as parameters. One or more of the below filter fields can be passed as parameters to the various API endpoints. The preferred terms for query filters are available and the reference table names are noted below.

The values passed to the filter fields are case insensitive
Filter Field Description Reference Table
ageEvent Subject's age event. This filter field can take multiple values and it will accept only exact values (case insensitive). lk_age_event
ageEventSpecify Subject's age event if not a preferred term. This filter field can take multiple values and it will accept only exact values (case insensitive). NA
ageUnit Subject's age unit. This filter field can take multiple values and it will accept only exact values (case insensitive). lk_time_unit
ancestralPopulation Subject's ancestral population. This filter field can take multiple values and it will accept only exact values (case insensitive). lk_ancestral_population
armAccession Study arm accession to which a subject is assigned. This filter field can take multiple values and it will accept only exact values (case insensitive). NA
armName Study arm name to which a subject is assigned.This filter field can take multiple values and it will accept partial match values (case insensitive). NA
biosampleAccession Biological sample accession. This filter field can take multiple values and it will accept only exact values (case insensitive). NA
biosampleSubtype Biological sample type if not a preferred term. This filter field can take multiple values and it will accept only exact values (case insensitive). NA
biosampleType Biological sample type. This filter field can take multiple values and it will accept only exact values (case insensitive). lk_sample_type
clinical Flag to indicate clincal trial status. This filter field will take a single exact value (case insensitive). Boolean
ethnicity Subject's ethnicity. This filter field can take multiple values and it will accept only exact values (case insensitive). lk_ethnicity
experimentAccession Experiment accession. This filter field can take multiple values and it will accept only exact values (case insensitive). NA
expsampleAccession Experiment sample accession. This filter field can take multiple values and it will accept only exact values (case insensitive). NA
gender Subject's gender. This filter field can take multiple values and it will accept only exact values (case insensitive). lk_gender
maxSubjectAge Subject's maximum age value. This filter field will take a single exact numeric value and the condition will be "equal to (=)". NA
maxSubjectAgeGte Subject's maximum age value. This filter field will take a single exact numeric value and the condition will be "greater than and equal to (>=)". NA
maxSubjectAgeLte Subject's maximum age value. This filter field will take a single exact numeric value and the condition will be "less than and equal to (<=)". NA
maxSubjectAgeGt Subject's maximum age value. This filter field will take a single exact numeric value and the condition will be "greater than (>)". NA
maxSubjectAgeLt Subject's maximum age value. This filter field will take a single exact numeric value and the condition will be "less than (<)". NA
minSubjectAge Subject's minimum age value. This filter field will take a single exact numeric value and the condition will be "equal to (=)". NA
minSubjectAgeGte Subject's minimum age value. This filter field will take a single exact numeric value and the condition will be "greater than and equal to (>=)". NA
minSubjectAgeLte Subject's minimum age value. This filter field will take a single exact numeric value and the condition will be "less than and equal to (<=)". NA
minSubjectAgeGt Subject's minimum age value. This filter field will take a single exact numeric value and the condition will be "greater than (>)". NA
minSubjectAgeLt Subject's minimum age value. This filter field will take a single exact numeric value and the condition will be "less than (<)". NA
measurementTechnique Experiment Measurement Technique. This filter field can take multiple values and it will accept only exact values (case insensitive). lk_exp_measurement_tech
plannedVisitAccession Study Planned Visit Accession. This filter field can take multiple values and it will accept only exact values (case insensitive). NA
race Subject's race. This filter field can take multiple values and it will accept only exact values (case insensitive). lk_race
raceSpecify Subject's race if non-preferred values were used. This filter field can take multiple values and it will accept only exact values (case insensitive). NA
species Subject's species. This filter field can take multiple values and it will accept only exact values (case insensitive). lk_species
strain Non-human subject strain. This filter field can take multiple values and it will accept only exact values (case insensitive). NA
studyAccession Study accession. This filter field can take multiple values and it will accept only exact values (case insensitive). NA
studyTimeCollected Sample's collection time in study timeline normalized per subject. This filter field will take a single exact numeric value and the condition will be "equal to (=)". NA
studyTimeCollectedGte Sample's collection time in study timeline normalized per subject. This filter field will take a single exact numeric value and the condition will be "greater than and equal to (>=)". NA
studyTimeCollectedLte Sample's collection time in study timeline normalized per subject. This filter field will take a single exact numeric value and the condition will be "less than and equal to (<=)". NA
studyTimeCollectedGt Sample's collection time in study timeline normalized per subject. This filter field will take a single exact numeric value and the condition will be "greater than (>)". NA
studyTimeCollectedLt Sample's collection time in study timeline normalized per subject. This filter field will take a single exact numeric value and the condition will be "less than (<)". NA
studyTimeCollectedUnit Sample study time collected unit. This filter field can take multiple values and it will take exact values (case insensitive). lk_time_unit
studyTimeT0Event Sample study time collected milestone or point of reference. This filter field can take multiple values and it will take exact values (case insensitive). lk_t0_event
studyTimeT0EventSpecify Sample study time collected milestone or point of reference if non-preferred tersm were used. This filter field can take multiple values and it will take exact values (case insensitive). NA
subjectAccession Subject accession. This filter field can take multiple values and it will accept only exact values (case insensitive). NA
studyTitle Study title. This filter field can take multiple values and it will take partial values (case insensitive) NA
subjectPhenotype Subject phenotype or description. This filter field can take multiple values and it will take exact values (case insensitive) NA
treatmentAccession Treatment accession. This filter field can take multiple values and it will accept partial match values (case insensitive). NA
format Query API format. This filter field will take a single exact value. The valid values for this field are: json and tsv. NA

Any of the shell scripts below can be copied to a .sh file and executed at the command prompt of a terminal and the output can be directed to a file. (Please replace the REPLACE_WITH_USERNAME with your username and REPLACE_WITH_PASSWORD with your password)

Example of a request passing multiple parameters:

#!/bin/bash

export token=`curl -X POST https://auth.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD" 2>&1  | fgrep '"token"' | sed -e 's/^.*"token" : "//;s/".*$//'`

curl -k -H "Authorization: bearer $token" "https://api.immport.org/data/query/result/pcr?studyAccession=SDY165&studyTimeCollectedGte=95.5&subjectPhenotype=Healthy%20volunteer"

[ {
  "resultId" : 40875,
  "ageEvent" : "Other",
  "ageEventSpecify" : "subject is atleast 18 years or older",
  "ageUnit" : "Years",
  "ancestralPopulation" : null,
  "armAccession" : "ARM743",
  "armName" : "Healthy_volunteer",
  "biosampleAccession" : "BS661596",
  "biosampleType" : "Cell",
  "biosampleSubtype" : "undividing B cells",
  "clinical" : "N",
  "comments" : "Legacy data copied from Threshold_Cycles column to Expression_Value column, and Expression_Unit column = Ct (where null). See ID-1609 for details.",
  "ethnicity" : "Other",
  "experimentAccession" : "EXP11754",
  "expsampleAccession" : "ES714478",
  "gender" : "Unknown",
  "geneId" : "6222",
  "geneName" : "ribosomal protein S18",
  "geneSymbol" : "RPS18",
  "maxSubjectAge" : 18.00,
  "measurementTechnique" : "Q-PCR",
  "minSubjectAge" : 18.00,
  "otherGeneAccession" : null,
  "plannedVisitAccession" : "PV3039",
  "race" : "Unknown",
  "raceSpecify" : null,
  "repositoryAccession" : null,
  "repositoryName" : null,
  "species" : "Homo sapiens",
  "strain" : null,
  "studyAccession" : "SDY165",
  "studyTitle" : "Characterization of in vitro Stimulated B Cells from Human Subjects",
  "studyTimeCollected" : 96.00,
  "studyTimeCollectedUnit" : "Hours",
  "studyTimeT0Event" : "Time of initial treatment",
  "studyTimeT0EventSpecify" : null,
  "subjectAccession" : "SUB119214",
  "subjectPhenotype" : "Healthy volunteer",
  "unitPreferred" : null,
  "unitReported" : "Ct",
  "valuePreferred" : null,
  "valueReported" : "15.2938",
  "treatmentAccession" : null
}, {
  "resultId" : 40876,
  "ageEvent" : "Other",
  "ageEventSpecify" : "subject is atleast 18 years or older",
  "ageUnit" : "Years",
  "ancestralPopulation" : null,
  "armAccession" : "ARM743",
  "armName" : "Healthy_volunteer",
  "biosampleAccession" : "BS661596",
  "biosampleType" : "Cell",
  "biosampleSubtype" : "undividing B cells",
  "clinical" : "N",
  "comments" : "Legacy data copied from Threshold_Cycles column to Expression_Value column, and Expression_Unit column = Ct (where null). See ID-1609 for details.",
  "ethnicity" : "Other",
  "experimentAccession" : "EXP11754",
  "expsampleAccession" : "ES714479",
  "gender" : "Unknown",
  "geneId" : "6222",
  "geneName" : "ribosomal protein S18",
  "geneSymbol" : "RPS18",
  "maxSubjectAge" : 18.00,
  "measurementTechnique" : "Q-PCR",
  "minSubjectAge" : 18.00,
  "otherGeneAccession" : null,
  "plannedVisitAccession" : "PV3039",
  "race" : "Unknown",
  "raceSpecify" : null,
  "repositoryAccession" : null,
  "repositoryName" : null,
  "species" : "Homo sapiens",
  "strain" : null,
  "studyAccession" : "SDY165",
  "studyTitle" : "Characterization of in vitro Stimulated B Cells from Human Subjects",
  "studyTimeCollected" : 96.00,
  "studyTimeCollectedUnit" : "Hours",
  "studyTimeT0Event" : "Time of initial treatment",
  "studyTimeT0EventSpecify" : null,
  "subjectAccession" : "SUB119214",
  "subjectPhenotype" : "Healthy volunteer",
  "unitPreferred" : null,
  "unitReported" : "Ct",
  "valuePreferred" : null,
  "valueReported" : "14.7243",
  "treatmentAccession" : null
}, {
  "resultId" : 40877,
  "ageEvent" : "Other",
  "ageEventSpecify" : "subject is atleast 18 years or older",
  "ageUnit" : "Years",
  "ancestralPopulation" : null,
  "armAccession" : "ARM743",
  "armName" : "Healthy_volunteer",
  "biosampleAccession" : "BS661596",
  "biosampleType" : "Cell",
  "biosampleSubtype" : "undividing B cells",
  "clinical" : "N",
  "comments" : "Legacy data copied from Threshold_Cycles column to Expression_Value column, and Expression_Unit column = Ct (where null). See ID-1609 for details.",
  "ethnicity" : "Other",
  "experimentAccession" : "EXP11754",
  "expsampleAccession" : "ES714480",
  "gender" : "Unknown",
  "geneId" : "6222",
  "geneName" : "ribosomal protein S18",
  "geneSymbol" : "RPS18",
  "maxSubjectAge" : 18.00,
  "measurementTechnique" : "Q-PCR",
  "minSubjectAge" : 18.00,
  "otherGeneAccession" : null,
  "plannedVisitAccession" : "PV3039",
  "race" : "Unknown",
  "raceSpecify" : null,
  "repositoryAccession" : null,
  "repositoryName" : null,
  "species" : "Homo sapiens",
  "strain" : null,
  "studyAccession" : "SDY165",
  "studyTitle" : "Characterization of in vitro Stimulated B Cells from Human Subjects",
  "studyTimeCollected" : 96.00,
  "studyTimeCollectedUnit" : "Hours",
  "studyTimeT0Event" : "Time of initial treatment",
  "studyTimeT0EventSpecify" : null,
  "subjectAccession" : "SUB119214",
  "subjectPhenotype" : "Healthy volunteer",
  "unitPreferred" : null,
  "unitReported" : "Ct",
  "valuePreferred" : null,
  "valueReported" : "14.7623",
  "treatmentAccession" : null
},......
The request above will return PCR result data because the endpoint is https://api.immport.org/data/query/result/pcr.

The filter criteria studyAccession=SDY165&studyTimeCollectedGte=95.5&subjectPhenotype=Healthy%20volunteer that will be executed on the PCR data will be study_accession = 'SDY165' and study_time_collected >= 95.5 and subject_phenotype='Healthy volunteer'

The response will be an array of PCR result data that satisfy the filter criteria. (The request has three filter conditions but you can have as many filter conditions as required)

Example of a request passing a parameter with multiple values:

#!/bin/bash

export token=`curl -X POST https://auth.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD" 2>&1  | fgrep '"token"' | sed -e 's/^.*"token" : "//;s/".*$//'`

curl -k -H "Authorization: bearer $token" "https://api.immport.org/data/query/result/neutAbTiter?studyAccession=SDY89,SDY180&expsampleAccession=ES588503,ES588504,ES717687"

[ {
  "resultId" : 1597,
  "ageEvent" : "Age at enrollment",
  "ageEventSpecify" : null,
  "ageUnit" : "Years",
  "ancestralPopulation" : null,
  "armAccession" : "ARM566",
  "armName" : "Energix-B",
  "biosampleAccession" : "BS632077",
  "biosampleType" : "Serum",
  "biosampleSubtype" : null,
  "clinical" : "N",
  "comments" : null,
  "ethnicity" : "Not Hispanic or Latino",
  "experimentAccession" : "EXP10671",
  "expsampleAccession" : "ES588503",
  "gender" : "Female",
  "maxSubjectAge" : 52.00,
  "measurementTechnique" : "Virus Neutralization",
  "minSubjectAge" : 52.00,
  "plannedVisitAccession" : "PV1872",
  "race" : "White",
  "raceSpecify" : null,
  "repositoryAccession" : null,
  "repositoryName" : null,
  "species" : "Homo sapiens",
  "strain" : null,
  "studyAccession" : "SDY89",
  "studyTitle" : "Systems Biology Analysis of the response to  Licensed Hepatitis B Vaccine (Engerix-B) (see companion study SDY690)",
  "studyTimeCollected" : 28.00,
  "studyTimeCollectedUnit" : "Days",
  "studyTimeT0Event" : "Time of initial vaccine administration",
  "studyTimeT0EventSpecify" : null,
  "subjectAccession" : "SUB114737",
  "subjectPhenotype" : "Healthy",
  "unitPreferred" : null,
  "unitReported" : null,
  "valuePreferred" : null,
  "valueReported" : "1",
  "virusStrainPreferred" : null,
  "virusStrainReported" : "Anti-HBs",
  "treatmentAccession" : "TRT41"
},....
The request above will return Neutralizing antibody titer result data (virus neutralization) because the endpoint is https://api.immport.org/data/query/result/neutAbTiter.

The filter criteria studyAccession=SDY89,SDY180&expsampleAccession=ES588503,ES588504,ES717687&maxSubjectAgeGt=26 that will be executed on the neutralizing antibody titer result data will be study_accession in ('SDY89','SDY180') and expsample_accession in ('ES588503','ES588504','ES717687').

For any filter condition that can take multiple values, the values specified should be comma separated or you can provide it as '&' separated (e.g. studyAccession=SDY89&studyAccession=SDY180). The response will be an array of neutralizing antibody titer result data that satisfy the filter criteria.

Example of a request passing a parameter that has a numeric value:

#!/bin/bash

export token=`curl -X POST https://auth.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD" 2>&1  | fgrep '"token"' | sed -e 's/^.*"token" : "//;s/".*$//'`

curl -k -H "Authorization: bearer $token" "https://api.immport.org/data/query/result/mbaa?studyAccession=SDY111&minSubjectAgeGte=63.9"

[ {
  "resultId" : 9589,
  "ageEvent" : "Age at initial vaccine administration",
  "ageEventSpecify" : null,
  "ageUnit" : "Years",
  "ancestralPopulation" : null,
  "analytePreferred" : "CD40LG",
  "analyteReported" : "CD40L",
  "armAccession" : "ARM641",
  "armName" : "Vaccine cohort 2011",
  "assayGroupId" : null,
  "assayId" : "P01",
  "biosampleAccession" : "BS689619",
  "biosampleType" : "Other",
  "biosampleSubtype" : null,
  "clinical" : "N",
  "comments" : null,
  "concentrationUnitPreferred" : null,
  "concentrationUnitReported" : "pg/ml",
  "concentrationValuePreferred" : null,
  "concentrationValueReported" : "35.92",
  "ethnicity" : "Not Hispanic or Latino",
  "experimentAccession" : "EXP13361",
  "gender" : "Male",
  "maxSubjectAge" : 63.90,
  "measurementTechnique" : "Luminex xMAP",
  "mfi" : "347.75",
  "mfiCoordinate" : null,
  "minSubjectAge" : 63.90,
  "plannedVisitAccession" : "PV1945",
  "race" : "White",
  "raceSpecify" : null,
  "repositoryAccession" : null,
  "repositoryName" : null,
  "species" : "Homo sapiens",
  "strain" : null,
  "studyAccession" : "SDY111",
  "studyTitle" : "VZV vaccination in the elderly",
  "studyTimeCollected" : 0.00,
  "studyTimeCollectedUnit" : "Days",
  "studyTimeT0Event" : "Time of initial vaccine administration",
  "studyTimeT0EventSpecify" : null,
  "sourceAccession" : "ES736348",
  "sourceType" : "EXPSAMPLE",
  "subjectAccession" : "SUB116437",
  "subjectPhenotype" : "Non-twin",
  "treatmentAccession" : "TRT255"
}, {
  "resultId" : 9590,
  "ageEvent" : "Age at initial vaccine administration",
  "ageEventSpecify" : null,
  "ageUnit" : "Years",
  "ancestralPopulation" : null,
  "analytePreferred" : "CXCL5",
  "analyteReported" : "ENA78",
  "armAccession" : "ARM641",
  "armName" : "Vaccine cohort 2011",
  "assayGroupId" : null,
  "assayId" : "P01",
  "biosampleAccession" : "BS689619",
  "biosampleType" : "Other",
  "biosampleSubtype" : null,
  "clinical" : "N",
  "comments" : null,
  "concentrationUnitPreferred" : null,
  "concentrationUnitReported" : "pg/ml",
  "concentrationValuePreferred" : null,
  "concentrationValueReported" : "47",
  "ethnicity" : "Not Hispanic or Latino",
  "experimentAccession" : "EXP13361",
  "gender" : "Male",
  "maxSubjectAge" : 63.90,
  "measurementTechnique" : "Luminex xMAP",
  "mfi" : "202",
  "mfiCoordinate" : null,
  "minSubjectAge" : 63.90,
  "plannedVisitAccession" : "PV1945",
  "race" : "White",
  "raceSpecify" : null,
  "repositoryAccession" : null,
  "repositoryName" : null,
  "species" : "Homo sapiens",
  "strain" : null,
  "studyAccession" : "SDY111",
  "studyTitle" : "VZV vaccination in the elderly",
  "studyTimeCollected" : 0.00,
  "studyTimeCollectedUnit" : "Days",
  "studyTimeT0Event" : "Time of initial vaccine administration",
  "studyTimeT0EventSpecify" : null,
  "sourceAccession" : "ES736348",
  "sourceType" : "EXPSAMPLE",
  "subjectAccession" : "SUB116437",
  "subjectPhenotype" : "Non-twin",
  "treatmentAccession" : "TRT255"
}, {
  "resultId" : 9591,
  "ageEvent" : "Age at initial vaccine administration",
  "ageEventSpecify" : null,
  "ageUnit" : "Years",
  "ancestralPopulation" : null,
  "analytePreferred" : "CCL11",
  "analyteReported" : "EOTAXIN",
  "armAccession" : "ARM641",
  "armName" : "Vaccine cohort 2011",
  "assayGroupId" : null,
  "assayId" : "P01",
  "biosampleAccession" : "BS689619",
  "biosampleType" : "Other",
  "biosampleSubtype" : null,
  "clinical" : "N",
  "comments" : null,
  "concentrationUnitPreferred" : null,
  "concentrationUnitReported" : "pg/ml",
  "concentrationValuePreferred" : null,
  "concentrationValueReported" : "32.34",
  "ethnicity" : "Not Hispanic or Latino",
  "experimentAccession" : "EXP13361",
  "gender" : "Male",
  "maxSubjectAge" : 63.90,
  "measurementTechnique" : "Luminex xMAP",
  "mfi" : "624",
  "mfiCoordinate" : null,
  "minSubjectAge" : 63.90,
  "plannedVisitAccession" : "PV1945",
  "race" : "White",
  "raceSpecify" : null,
  "repositoryAccession" : null,
  "repositoryName" : null,
  "species" : "Homo sapiens",
  "strain" : null,
  "studyAccession" : "SDY111",
  "studyTitle" : "VZV vaccination in the elderly",
  "studyTimeCollected" : 0.00,
  "studyTimeCollectedUnit" : "Days",
  "studyTimeT0Event" : "Time of initial vaccine administration",
  "studyTimeT0EventSpecify" : null,
  "sourceAccession" : "ES736348",
  "sourceType" : "EXPSAMPLE",
  "subjectAccession" : "SUB116437",
  "subjectPhenotype" : "Non-twin",
  "treatmentAccession" : "TRT255"
},....
The request above will return MBAA result data because the endpoint is https://api.immport.org/data/query/result/mbaa.

The filter criteria studyAccession=SDY111&minSubjectAgeGte=63.9 that will be executed on the MBAA result data will be study_accession = 'SDY111' and min_subject_age >= 63.9.

For any filter condition that can take numeric value, the values specified should be a number and depending on the suffix Gte (Greater than and equal to), Lte (Less than and equal to), Gt (Greater than), Lt (Less than ) the operation will be determined. The response will be an array of MBAA result data that satisfy the filter criteria.

Example of a request passing a partial value to a parameter like studyTitle:


#!/bin/bash

export token=`curl -X POST https://auth.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD" 2>&1  | fgrep '"token"' | sed -e 's/^.*"token" : "//;s/".*$//'`

curl -k -H "Authorization: bearer $token" "https://api.immport.org/data/query/result/hlaTyping?studyTitle=smallpox%20vaccine"

[ {
  "resultId" : 68533,
  "allele1" : "A*020101",
  "allele2" : "A*020101",
  "ageEvent" : "Age at enrollment",
  "ageEventSpecify" : null,
  "ageUnit" : "Years",
  "ancestralPopulation" : null,
  "armAccession" : "ARM51",
  "armName" : "Control Group",
  "biosampleAccession" : "BS255367",
  "biosampleType" : "DNA",
  "biosampleSubtype" : null,
  "clinical" : "N",
  "comments" : null,
  "ethnicity" : "Not Specified",
  "experimentAccession" : "EXP4730",
  "expsampleAccession" : "ES145152",
  "gender" : "Female",
  "maxSubjectAge" : 25.00,
  "measurementTechnique" : "HLA Typing",
  "minSubjectAge" : 25.00,
  "plannedVisitAccession" : "PV1250",
  "race" : "White",
  "raceSpecify" : null,
  "repositoryAccession" : null,
  "repositoryName" : null,
  "resultSetId" : 107322,
  "species" : "Homo sapiens",
  "strain" : null,
  "studyAccession" : "SDY26",
  "studyTitle" : "Identify polymorphisms associated with risk for the development of myopericarditis following smallpox vaccine",
  "studyTimeCollected" : 1.00,
  "studyTimeCollectedUnit" : "Days",
  "studyTimeT0Event" : "Not Specified",
  "studyTimeT0EventSpecify" : null,
  "subjectAccession" : "SUB82339",
  "subjectPhenotype" : "Control",
  "treatmentAccession" : null
}, {
  "resultId" : 68534,
  "allele1" : "B*4001",
  "allele2" : "B*440201",
  "ageEvent" : "Age at enrollment",
  "ageEventSpecify" : null,
  "ageUnit" : "Years",
  "ancestralPopulation" : null,
  "armAccession" : "ARM51",
  "armName" : "Control Group",
  "biosampleAccession" : "BS255367",
  "biosampleType" : "DNA",
  "biosampleSubtype" : null,
  "clinical" : "N",
  "comments" : null,
  "ethnicity" : "Not Specified",
  "experimentAccession" : "EXP4730",
  "expsampleAccession" : "ES145152",
  "gender" : "Female",
  "maxSubjectAge" : 25.00,
  "measurementTechnique" : "HLA Typing",
  "minSubjectAge" : 25.00,
  "plannedVisitAccession" : "PV1250",
  "race" : "White",
  "raceSpecify" : null,
  "repositoryAccession" : null,
  "repositoryName" : null,
  "resultSetId" : 107322,
  "species" : "Homo sapiens",
  "strain" : null,
  "studyAccession" : "SDY26",
  "studyTitle" : "Identify polymorphisms associated with risk for the development of myopericarditis following smallpox vaccine",
  "studyTimeCollected" : 1.00,
  "studyTimeCollectedUnit" : "Days",
  "studyTimeT0Event" : "Not Specified",
  "studyTimeT0EventSpecify" : null,
  "subjectAccession" : "SUB82339",
  "subjectPhenotype" : "Control",
  "treatmentAccession" : null
},....
The request above will return HLA typing result data because the endpoint is https://api.immport.org/data/query/result/hlaTyping.

The filter criteria studyTitle=smallpox%20vaccine that will be executed on the HLA typing result data will be study_title like '%smallpox vaccine%'.

The search will be case insensitive and any HLA typing where the study title has 'smallpox vaccine' will be returned in the response.

The response will be an array of HLA typing result data that satisfy the filter criteria.

Example of a request on the filepath endpoint:

#!/bin/bash

export token=`curl -X POST https://auth.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD" 2>&1  | fgrep '"token"' | sed -e 's/^.*"token" : "//;s/".*$//'`

curl -k -H "Authorization: bearer $token" "https://api.immport.org/data/query/result/filePath?studyAccession=SDY208"


[ {
  "filePathId" : "388647_ES736618_BS689943",
  "fileInfoId" : 388647,
  "fileDetail" : "Virus neutralization result",
  "filesizeBytes" : 615,
  "fileName" : "Virus_Neutralization_Results.388647.txt",
  "originalFileName" : "Virus_Neutralization_Results.txt",
  "sourceType" : "EXPSAMPLE",
  "sourceAccession" : "ES736618",
  "experimentAccession" : "EXP13365",
  "measurementTechnique" : "Hemagglutination Inhibition",
  "studyAccession" : "SDY208",
  "clinical" : "N",
  "studyTitle" : "Serological Memory and Long-term Protection to Novel H1N1 Influenza Virus After Skin Vaccination",
  "biosampleAccession" : "BS689943",
  "biosampleType" : "Tissue",
  "biosampleSubtype" : null,
  "studyTimeCollected" : 154.0,
  "studyTimeCollectedUnit" : "Days",
  "studyTimeT0Event" : "Time of initial vaccine administration",
  "studyTimeT0EventSpecify" : null,
  "plannedVisitAccession" : "PV2442",
  "subjectAccession" : "SUB120519",
  "ethnicity" : null,
  "gender" : "Female",
  "race" : null,
  "raceSpecify" : null,
  "species" : "Mus musculus",
  "strain" : null,
  "armAccession" : "ARM884",
  "armName" : "Microneedle vaccination- 5 ug inactivated A/California/04/09 virus, Challenged: 10x LD50 A/California/04/09 virus",
  "ageEvent" : "Age at enrollment",
  "ageEventSpecify" : null,
  "ageUnit" : "Weeks",
  "maxSubjectAge" : 6.0,
  "minSubjectAge" : 6.0,
  "subjectPhenotype" : "Specific-pathogen free",
  "filePath" : "/SDY208/ResultFiles/Virus_neutralization_result/Virus_Neutralization_Results.388647.txt"
}, {
  "filePathId" : "388647_ES736619_BS689944",
  "fileInfoId" : 388647,
  "fileDetail" : "Virus neutralization result",
  "filesizeBytes" : 615,
  "fileName" : "Virus_Neutralization_Results.388647.txt",
  "originalFileName" : "Virus_Neutralization_Results.txt",
  "sourceType" : "EXPSAMPLE",
  "sourceAccession" : "ES736619",
  "experimentAccession" : "EXP13365",
  "measurementTechnique" : "Hemagglutination Inhibition",
  "studyAccession" : "SDY208",
  "clinical" : "N",
  "studyTitle" : "Serological Memory and Long-term Protection to Novel H1N1 Influenza Virus After Skin Vaccination",
  "biosampleAccession" : "BS689944",
  "biosampleType" : "Tissue",
  "biosampleSubtype" : null,
  "studyTimeCollected" : 154.0,
  "studyTimeCollectedUnit" : "Days",
  "studyTimeT0Event" : "Time of initial vaccine administration",
  "studyTimeT0EventSpecify" : null,
  "plannedVisitAccession" : "PV2442",
  "subjectAccession" : "SUB120520",
  "ethnicity" : null,
  "gender" : "Female",
  "race" : null,
  "raceSpecify" : null,
  "species" : "Mus musculus",
  "strain" : null,
  "armAccession" : "ARM885",
  "armName" : "Subcutaneous vaccination- 5 ug inactivated A/California/04/09 virus, Challenged: 10x LD50 A/California/04/09 virus",
  "ageEvent" : "Age at enrollment",
  "ageEventSpecify" : null,
  "ageUnit" : "Weeks",
  "maxSubjectAge" : 6.0,
  "minSubjectAge" : 6.0,
  "subjectPhenotype" : "Specific-pathogen free",
  "filePath" : "/SDY208/ResultFiles/Virus_neutralization_result/Virus_Neutralization_Results.388647.txt"
},.........
The request above will return the paths to result files because the endpoint is https://api.immport.org/data/query/result/filePath.

The filter criteria studyAccession=SDY208 that will be executed on the result data will be study_accession = 'SDY208'.

The response will be an array of result file metadata and its corresponding file paths.

This response can be an input into the File Download API which will download all the unique list of files in the response.

Example of a request passing the format parameter to return a tsv response:

#!/bin/bash

export token=`curl -X POST https://auth.immport.org/auth/token -d username="testadmin" -d password="Biscadmin2014#" 2>&1  | fgrep '"token"' | sed -e 's/^.*"token" : "//;s/".*$//'`

curl -k -H "Authorization: bearer $token" "https://api.immport.org/data/query/result/filePath?format=tsv&studyAccession=SDY208"
ageEvent    ageEventSpecify ageUnit armAccession    armName biosampleAccession  biosampleSubtype    biosampleType   clinical    ethnicity   experimentAccession fileDetail  fileInfoId  fileName    filePath    filePathId  filesizeBytes   gender  maxSubjectAge   measurementTechnique    minSubjectAge   originalFileName    plannedVisitAccession   race    raceSpecify sourceAccession sourceType  species strain  studyAccession  studyTimeCollected  studyTimeCollectedUnit  studyTimeT0Event    studyTimeT0EventSpecify studyTitle  subjectAccession    subjectPhenotype
Age at enrollment       Weeks   ARM884  Microneedle vaccination- 5 ug inactivated A/California/04/09 virus, Challenged: 10x LD50 A/California/04/09 virus   BS689943        Tissue  N       EXP13365    Virus neutralization result 388647  Virus_Neutralization_Results.388647.txt /SDY208/ResultFiles/Virus_neutralization_result/Virus_Neutralization_Results.388647.txt 388647_ES736618_BS689943    615 Female  6.0 Hemagglutination Inhibition 6.0 Virus_Neutralization_Results.txt    PV2442          ES736618    EXPSAMPLE   Mus musculus        SDY208  154.0   Days    Time of initial vaccine administration      Serological Memory and Long-term Protection to Novel H1N1 Influenza Virus After Skin Vaccination    SUB120519   Specific-pathogen free
Age at enrollment       Weeks   ARM885  Subcutaneous vaccination- 5 ug inactivated A/California/04/09 virus, Challenged: 10x LD50 A/California/04/09 virus  BS689944        Tissue  N       EXP13365    Virus neutralization result 388647  Virus_Neutralization_Results.388647.txt /SDY208/ResultFiles/Virus_neutralization_result/Virus_Neutralization_Results.388647.txt 388647_ES736619_BS689944    615 Female  6.0 Hemagglutination Inhibition 6.0 Virus_Neutralization_Results.txt    PV2442          ES736619    EXPSAMPLE   Mus musculus        SDY208  154.0   Days    Time of initial vaccine administration      Serological Memory and Long-term Protection to Novel H1N1 Influenza Virus After Skin Vaccination    SUB120520   Specific-pathogen free
Age at enrollment       Weeks   ARM886  Uncoated microneedle vaccination-  Placebo, Challenged: 10x LD50 A/California/04/09 virus   BS689945        Tissue  N       EXP13365    Virus neutralization result 388647  Virus_Neutralization_Results.388647.txt /SDY208/ResultFiles/Virus_neutralization_result/Virus_Neutralization_Results.388647.txt 388647_ES736620_BS689945    615 Female  6.0 Hemagglutination Inhibition 6.0 Virus_Neutralization_Results.txt    PV2442          ES736620    EXPSAMPLE   Mus musculus        SDY208  154.0   Days    Time of initial vaccine administration      Serological Memory and Long-term Protection to Novel H1N1 Influenza Virus After Skin Vaccination    SUB120521   Specific-pathogen free
Age at enrollment       Weeks   ARM887  Uncoated microneedle vaccination-  Placebo, Challenged: Not infected    BS689946        Tissue  N       EXP13365    Virus neutralization result 388647  Virus_Neutralization_Results.388647.txt /SDY208/ResultFiles/Virus_neutralization_result/Virus_Neutralization_Results.388647.txt 388647_ES736621_BS689946    615 Female  6.0 Hemagglutination Inhibition 6.0 Virus_Neutralization_Results.txt    PV2442          ES736621    EXPSAMPLE   Mus musculus        SDY208  154.0   Days    Time of initial vaccine administration      Serological Memory and Long-term Protection to Novel H1N1 Influenza Virus After Skin Vaccination    SUB120522   Specific-pathogen free
Age at enrollment       Weeks   ARM884  Microneedle vaccination- 5 ug inactivated A/California/04/09 virus, Challenged: 10x LD50 A/California/04/09 virus   BS689943        Tissue  N       EXP13368    Image Histology result  388650  DK11-M-Histo.388650.pdf /SDY208/ResultFiles/Image_Histology_result/DK11-M-Histo.388650.pdf  388650_ES736622_BS689943    211383  Female  6.0 Microscopy  6.0 DK11-M-Histo.pdf    PV2442          ES736622    EXPSAMPLE   Mus musculus        SDY208  154.0   Days    Time of initial vaccine administration      Serological Memory and Long-term Protection to Novel H1N1 Influenza Virus After Skin Vaccination    SUB120519   Specific-pathogen free
Age at enrollment       Weeks   ARM885  Subcutaneous vaccination- 5 ug inactivated A/California/04/09 virus, Challenged: 10x LD50 A/California/04/09 virus  BS689944        Tissue  N       EXP13368    Image Histology result  388650  DK11-M-Histo.388650.pdf /SDY208/ResultFiles/Image_Histology_result/DK11-M-Histo.388650.pdf  388650_ES736623_BS689944    211383  Female  6.0 Microscopy  6.0 DK11-M-Histo.pdf    PV2442          ES736623    EXPSAMPLE   Mus musculus        SDY208  154.0   Days    Time of initial vaccine administration      Serological Memory and Long-term Protection to Novel H1N1 Influenza Virus After Skin Vaccination    SUB120520   Specific-pathogen free
Age at enrollment       Weeks   ARM886  Uncoated microneedle vaccination-  Placebo, Challenged: 10x LD50 A/California/04/09 virus   BS689945        Tissue  N       EXP13368    Image Histology result  388650  DK11-M-Histo.388650.pdf /SDY208/ResultFiles/Image_Histology_result/DK11-M-Histo.388650.pdf  388650_ES736624_BS689945    211383  Female  6.0 Microscopy  6.0 DK11-M-Histo.pdf    PV2442          ES736624    EXPSAMPLE   Mus musculus        SDY208  154.0   Days    Time of initial vaccine administration      Serological Memory and Long-term Protection to Novel H1N1 Influenza Virus After Skin Vaccination    SUB120521   Specific-pathogen free
Age at enrollment       Weeks   ARM887  Uncoated microneedle vaccination-  Placebo, Challenged: Not infected    BS689946        Tissue  N       EXP13368    Image Histology result  388650  DK11-M-Histo.388650.pdf /SDY208/ResultFiles/Image_Histology_result/DK11-M-Histo.388650.pdf  388650_ES736625_BS689946    211383  Female  6.0 Microscopy  6.0 DK11-M-Histo.pdf    PV2442          ES736625    EXPSAMPLE   Mus musculus        SDY208  154.0   Days    Time of initial vaccine administration      Serological Memory and Long-term Protection to Novel H1N1 Influenza Virus After Skin Vaccination    SUB120522   Specific-pathogen free
The above request has a parameter format=tsv. If parameter is passed to any of the API endpoints mentioned above, the response will be returned as tab separated data.