Skip to content

How to Download Data

ImmPort provides multiple ways to download data — through the web interface or programmatically using APIs. Authentication is required to download data from ImmPort. You can register here.

Web Interface

Single File Download

  • Navigate to a study download page.
  • Click the Download icon next to a file.
  • The file will download directly through your browser using a secure, time-limited URL.

Study Download Page

Study Download Page

Multiple File Download

  • Select multiple files (across one or more studies) and add them to your Download Cart.
  • When you download the cart:
    • A background job is created to generate a ZIP archive containing all selected files.
    • A Signed CloudFront URL is created for the ZIP which expires in 7 days upon receipt.
  • You can refresh the cart status on the download page to check progress
  • You will receive an email notification once the download is ready.
  • Depending on the cart size, the process may take several minutes.

Study Download Page

Download Cart

Programmatic Access

GA4GH DRS API

GA4GH Data Repository Service (DRS) API is a generic interface to data repositories so data consumers, workflow systems, can access data objects in a single, standard way regardless of where they are stored and how they are managed. The primary functionality of DRS is to map a logical ID to a means for physically retrieving the data represented by the ID.

ImmPort has implemented the DRS API for accessing shared data in the following two access methods.

  • S3 Signed URL: An AWS S3 signed URL is generated for the given DRS ID. The URL expires after seven days. Files are stored in an S3 bucket in the AWS US-EAST-1 (N.Virginia) region.
  • Streaming URL: A streaming URL is generated for the given DRS ID to stream the file in bytes from the source.

The Immport DRS API endpoint requires an OAuth 2.0 bearer token to access them. Please refer below to the sample API call to retrieve a direct download URL for a single file using the GA4GH DRS API.

Sample API call to a DRS API endpoint

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 retrieve access endpoint UUIDs for the DRS URL that was retrieved in the previous example.

The first line is a POST to the authentication URL https://www.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 DRS URL https://drs.immport.org/ga4gh/drs/v1/objects/ddd17e17-e2d5-418a-8e6b-42487726b9a6 that is got from the FHIR endpoint response as shown above. The supports type of the related artifact has the drs url for each of the study file associated with the study,

The authentication token ("token") is passed in the HTTP header as shown.

The response will return two access UUIDs for the resource represented by the UUID ddd17e17-e2d5-418a-8e6b-42487726b9a6. This UUID represents the file PLN_2013-11-25_09-14-44.txt that contains Pollen data.

The above shell script or any code starting with #!/bin/bash can be copied to a .sh file (e.g. SDY1_DRS.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.)

#!/bin/bash

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

curl -k -H "Authorization: bearer $token" "https://drs.immport.org/ga4gh/drs/v1/objects/ddd17e17-e2d5-418a-8e6b-42487726b9a6"

Results 

{
"id" : "ddd17e17-e2d5-418a-8e6b-42487726b9a6",
"description" : "SDY1-PLN_2013-11-25_09-14-44.txt",
"created_time" : "2024-04-30T16:17:20Z",
"mime_type" : "text/plain",
"name" : "PLN_2013-11-25_09-14-44.txt",
"size" : 38327,
"updated_time" : "2024-04-30T16:17:20Z",
"checksums" : [ {
    "checksum" : "318c6e107b98a406fed3c2e906eb6996",
    "type" : "md5"
} ],
"self_uri" : "drs://drs.immport.org:/ddd17e17-e2d5-418a-8e6b-42487726b9a6",
"access_methods" : [ {
    "access_id" : "83097414-06f6-46d7-a7dc-ac6e5609ce2e",
    "type" : "https"
}, {
    "access_id" : "5e10e701-c48b-44da-9450-617d8b1f3a82",
    "type" : "s3",
    "region" : "US East (N. Virginia) us-east-1"
} ]
}

The above output returns two access method UUID:

  • Access Id for Streaming URL Endpoint (https) - 83097414-06f6-46d7-a7dc-ac6e5609ce2e
  • Access Id for S3 Signed URL Endpoint (s3) - 5e10e701-c48b-44da-9450-617d8b1f3a82

To get the Streaming URL Endpoint, use the streamimg access UUID as shown below:

#!/bin/bash

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

curl -k -H "Authorization: bearer $token" "https://drs.immport.org/ga4gh/drs/v1/objects/ddd17e17-e2d5-418a-8e6b-42487726b9a6/access/83097414-06f6-46d7-a7dc-ac6e5609ce2e"

Results 

{
    "url" : "https://drs.immport.org/ga4gh/drs/v1/stream/ddd17e17-e2d5-418a-8e6b-42487726b9a6/83097414-06f6-46d7-a7dc-ac6e5609ce2e"
}

The above streaming endpoint can stream the file to the specified destination e.g. cloud analysis platforms like Cavatica, Terra, etc

To get the S3 URL Endpoint, use the s3 access UUID as shown below:

#!/bin/bash

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

curl -k -H "Authorization: bearer $token" "https://drs.immport.org/ga4gh/drs/v1/objects/ddd17e17-e2d5-418a-8e6b-42487726b9a6/access/5e10e701-c48b-44da-9450-617d8b1f3a82"

Results

{
  "url" : "https://immport-strides-prod-shared-data.s3.amazonaws.com/SDY1/StudyFiles/PLN_2013-11-25_09-14-44.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240504T140525Z&X-Amz-SignedHeaders=host&X-Amz-Expires=26400&X-Amz-Credential=AKIAQ3E4VVSLOIIOEVAS%2F20240504%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=6ab32cba03769be778291e888a68f0755297a7ef264594269742f882e426da4d"
}

The above S3 endpoint can download the file to the specified destination e.g. cloud analysis platforms like Cavatica, Terra, etc

ImmPort Download Client

Download the ImmPort Download Client here.

ImmPort Download Client

You can download the client here

The ImmPort Download Client provides a command-line interface (CLI) to download files from ImmPort using the DRS (GA4GH Data Repository Service) standard transfer methods.

It authenticates the user with ImmPort login credentilas, processes a manifest file, and downloads all files listed in the manifest to a specified output directory.

You can obtain a manifest file in one of the following ways:

  • From the Download Cart in the ImmPort UI
    After selecting multiple files across studies, click “Download Cart” → “Generate Manifest” to create a manifest file for programmatic download.

Generate Manifest File

Generate Manifest File

  • From a Study Download Page
    Each study page provides a ready-to-use manifest.
    Example: SDY230_DR58_manifest.txt as shown below.

Study Manifest File

Study Manifest File

  • Example Manifest Format
STUDY_ACCESSION FILE_NAME   FILE_TYPE   DRS_ID  MD5_CHECKSUM    FILESIZE_BYTES  PATH
SDY230  SDY230-DR58_table_count.txt release_file    81944983-0aaf-4b55-a1ef-e2681c8b258b    a4264284e7d57466b58e3e8a0510190e    2158    SDY230/SDY230-DR58_table_count.txt
SDY230  SDY230-DR58_summary.txt release_file    a3a2dbb7-0a77-4389-9816-401f07395d29    8dff2e784ea36b6695ca9326f442a293    129 SDY230/SDY230-DR58_summary.txt

Usage

immport-download-client \
  --user_name REPLACE_WITH_USERNAME \
  --password REPLACE_WITH_PASSWORD \
  --manifest ../test/manifest.txt \
  --output_directory ./output \
  --download_type drs