# Retrieving DICOM data from HealthImaging AWS HealthImaging offers representations of [https://www.dicomstandard.org/using/dicomweb/retrieve-wado-rs-and-wado-uri](https://www.dicomstandard.org/using/dicomweb/retrieve-wado-rs-and-wado-uri) APIs to retrieve data at the series and instance levels. With these APIs, it is possible to retrieve all metadata for a DICOM series from a HealthImaging [data store](getting-started-concepts.md#concept-data-store). It is also possible to retrieve a DICOM instance, DICOM instance metadata, and DICOM instance frames (pixel data). HealthImaging's `DICOMweb WADO-RS` APIs offer flexibility in how you retrieve data stored in HealthImaging and provide interoperability with legacy applications. **Important** HealthImaging stores DICOM data as [image sets](getting-started-concepts.md#concept-image-set). Use HealthImaging [cloud native actions](https://docs.aws.amazon.com/healthimaging/latest/APIReference/API_Operations.html) to manage and retrieve image sets. HealthImaging's DICOMweb APIs can be used to return image set information with DICOMweb-conformant responses. The APIs listed in this section are built in conformance to the DICOMweb (WADO-RS) standard for web-based medical imaging. Because they are representations of DICOMweb APIs, they are not offered through AWS CLI and AWS SDKs. The following table describes all HealthImaging representations of DICOMweb WADO-RS APIs available for retrieving data from HealthImaging. **HealthImaging representations of DICOMweb WADO-RS APIs** | Name | Description | | --- | --- | | GetDICOMSeriesMetadata | Retrieve DICOM instance metadata (.json file) for a DICOM series in a HealthImaging data store by specifying the Study and Series UIDs associated with a resource. See [Retrieve series metadata](dicomweb-retrieve-series-metadata.md). | | GetDICOMInstance | Retrieve a DICOM instance (.dcm file) from a HealthImaging data store by specifying the Series, Study, and Instance UIDs associated with a resource. See [Retrieve an instance](dicomweb-retrieve-instance.md). | | GetDICOMInstanceMetadata | Retrieve DICOM instance metadata (.json file) from a DICOM instance in a HealthImaging data store by specifying the Series, Study, and Instance UIDs associated with a resource. See [Retrieve instance metadata](dicomweb-retrieve-instance-metadata.md). | | GetDICOMInstanceFrames | Retrieve single or batch image frames (multipart request) from a DICOM instance in a HealthImaging data store by specifying the Series UID, Study UID, Instance UIDs, and frame numbers associated with a resource. See [Retrieve frames](dicomweb-retrieve-instance-frames.md). | **Topics** + [Getting a DICOM instance from HealthImaging](dicomweb-retrieve-instance.md) + [Getting DICOM instance metadata from HealthImaging](dicomweb-retrieve-instance-metadata.md) + [Getting DICOM series metadata from HealthImaging](dicomweb-retrieve-series-metadata.md) + [Getting DICOM instance frames from HealthImaging](dicomweb-retrieve-instance-frames.md) + [Getting DICOM bulkdata from HealthImaging](dicom-retrieve-bulkdata.md) # Getting a DICOM instance from HealthImaging Use the `GetDICOMInstance` action to retrieve a DICOM instance (`.dcm` file) from a HealthImaging [data store](getting-started-concepts.md#concept-data-store) by specifying the Series, Study, and Instance UIDs associated with the resource. The API will only return instances from primary image sets unless the optional [image set parameter](getting-started-concepts.md#concept-image-set) is provided. You can retrieve any instance (from primary or non-primary image sets) in the data store by specifying the `imageSetId` as a query parameter. DICOM data can be retrieved in either its stored transfer syntax or as uncompressed (ELE) format. **To get a DICOM instance (`.dcm`)** 1. Collect HealthImaging `datastoreId` and `imageSetId` parameter values. 1. Use the [https://docs.aws.amazon.com/healthimaging/latest/APIReference/API_GetImageSetMetadata.html](https://docs.aws.amazon.com/healthimaging/latest/APIReference/API_GetImageSetMetadata.html) action with the `datastoreId` and `imageSetId` parameter values to retrieve associated metadata values for `studyInstanceUID`, `seriesInstanceUID`, and `sopInstanceUID`. For more information, see [Getting image set metadata](get-image-set-metadata.md). 1. Construct a URL for the request using the values for `datastoreId`, `studyInstanceUID`, `seriesInstanceUID`, `sopInstanceUID`, and `imageSetId`. To view the entire URL path in the following example, scroll over the **Copy** button. The URL is of the form: ``` GET https://dicom-medical-imaging.region.amazonaws.com/datastore/datastore-id/studies/study-instance-uid/series/series-instance-uid/instances/sop-instance-uid?imageSetId=image-set-id ``` 1. Prepare and send your request. `GetDICOMInstance` uses a HTTP GET request with [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) signing protocol. The following code example uses the `curl` command line tool to get a DICOM instance (`.dcm` file) from HealthImaging. ------ #### [ Shell ] ``` curl --request GET \ 'https://dicom-medical-imaging.us-east-1.amazonaws.com/datastore/d9a2a515ab294163a2d2f4069eed584c/studies/1.3.6.1.4.1.5962.1.2.4.20040826285059.5457/series/1.3.6.1.4.1.5962.1.3.4.1.20040825185059.5457/instances/1.3.6.1.4.1.5962.1.1.4.1.1.20040826186059.5457?imageSetId=459e50687f121185f747b67bb60d1bc8' \ --aws-sigv4 'aws:amz:us-east-1:medical-imaging' \ --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \ --header "x-amz-security-token:$AWS_SESSION_TOKEN" \ --header 'Accept: application/dicom; transfer-syntax=1.2.840.10008.1.2.1' \ --output 'dicom-instance.dcm' ``` ------ **Note** The `transfer-syntax` UID is optional and defaults to Explicit VR Little Endian if not included. Supported transfer syntaxes include: Explicit VR Little Endian (ELE) - `1.2.840.10008.1.2.1` (default for lossless image frames) If `transfer-syntax=*` then the image frame(s) will be returned in the stored transfer syntax. High-Throughput JPEG 2000 with RPCL Options Image Compression (Lossless Only) - `1.2.840.10008.1.2.4.202` - if the instance is stored in HealthImaging as `1.2.840.10008.1.2.4.202` JPEG 2000 Lossless - `1.2.840.10008.1.2.4.90` - if the instance is stored in HealthImaging as lossless. JPEG Baseline (Process 1): Default Transfer Syntax for Lossy JPEG 8-bit Image Compression - `1.2.840.10008.1.2.4.50` - if the instance is stored in HealthImaging as `1.2.840.10008.1.2.4.50` JPEG 2000 Image Compression - `1.2.840.10008.1.2.4.91` - if the instance is stored in HealthImaging as `1.2.840.10008.1.2.4.91` High-Throughput JPEG 2000 Image Compression - `1.2.840.10008.1.2.4.203` - if the instance is stored in HealthImaging as `1.2.840.10008.1.2.4.203` JPEG XL Image Compression - `1.2.840.10008.1.2.4.112` - if the instance is stored in HealthImaging as `1.2.840.10008.1.2.4.112` Instances stored in HealthImaging with one or more image frames encoded in the MPEG family of [Transfer Syntaxes](supported-transfer-syntaxes.md) (which includes MPEG2, MPEG-4 AVC/H.264 and HEVC/H.265) may be retrieved with the corresponding transfer-syntax UID. For example, `1.2.840.10008.1.2.4.100` if the instance is stored as MPEG2 Main Profile Main Level. For more information, see [Supported transfer syntaxes](supported-transfer-syntaxes.md) and [Image frame decoding libraries for AWS HealthImaging](reference-libraries.md). # Getting DICOM instance metadata from HealthImaging Use the `GetDICOMInstanceMetadata` action to retrieve the metadata from a DICOM instance in a HealthImaging [ data store](getting-started-concepts.md#concept-data-store) by specifying the Series, Study, and Instance UIDs associated with the resource. The API will only return instance metadata from primary image sets unless the optional [ image set](getting-started-concepts.md#concept-image-set) parameter is provided. You can retrieve any instance metadata (from primary or non-primary image sets) in the data store by specifying the `imageSetId` as a query parameter. **To get DICOM instance metadata (`.json`)** 1. Collect HealthImaging `datastoreId` and `imageSetId` parameter values. 1. Use the [https://docs.aws.amazon.com/healthimaging/latest/APIReference/API_GetImageSetMetadata.html](https://docs.aws.amazon.com/healthimaging/latest/APIReference/API_GetImageSetMetadata.html) action with the `datastoreId` and `imageSetId` parameter values to retrieve associated metadata values for `studyInstanceUID`, `seriesInstanceUID`, and `sopInstanceUID`. For more information, see [Getting image set metadata](get-image-set-metadata.md). 1. Construct a URL for the request using the values for `datastoreId`, `studyInstanceUID`, `seriesInstanceUID`, `sopInstanceUID`, and `imageSetId`. To view the entire URL path in the following example, scroll over the **Copy** button. The URL is of the form: ``` GET https://dicom-medical-imaging.region.amazonaws.com/datastore/datastore-id/studies/study-instance-uid/series/series-instance-uid/instances/sop-instance-uid/metadata?imageSetId=image-set-id ``` 1. Prepare and send your request. `GetDICOMInstanceMetadata` uses a HTTP GET request with [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) signing protocol. The following code example uses the `curl` command line tool to get DICOM instance metadata (`.json` file) from HealthImaging. ------ #### [ Shell ] ``` curl --request GET \ 'https://dicom-medical-imaging.us-east-1.amazonaws.com/datastore/d9a2a515ab294163a2d2f4069eed584c/studies/1.3.6.1.4.1.5962.1.2.4.20040826285059.5457/series/1.3.6.1.4.1.5962.1.3.4.1.20040825185059.5457/instances/1.3.6.1.4.1.5962.1.1.4.1.1.20040826186059.5457/metadata?imageSetId=459e50687f121185f747b67bb60d1bc8' \ --aws-sigv4 'aws:amz:us-east-1:medical-imaging' \ --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \ --header "x-amz-security-token:$AWS_SESSION_TOKEN" \ --header 'Accept: application/dicom+json' ``` ------ **Note** The Transfer Syntax UID indicated in the metadata matches the Stored Transfer Syntax UID (`StoredTransferSyntaxUID`) in HealthImaging. # Getting DICOM series metadata from HealthImaging Use the `GetDICOMSeriesMetadata` action to retrieve the metadata for a DICOM series (`.json` file) from a HealthImaging [data store](getting-started-concepts.md#concept-data-store). You can retrieve series metadata for any primary [ image set](getting-started-concepts.md#concept-image-set) in the HealthImaging data store by specifying the Study and Series UIDs associated with the resource. You can retrieve series metadata for non-Primary image sets by providing the image set ID as a query parameter. The series metadata is returned in `DICOM JSON` format. **To get DICOM series metadata (`.json`)** 1. Collect HealthImaging `datastoreId` and `imageSetId` parameter values. 1. Construct a URL for the request using the values for `datastoreId`, `studyInstanceUID`, `seriesInstanceUID`, and optionally `imageSetId`. To view the entire URL path in the following example, scroll over the **Copy** button. The URL is of the form: ``` GET https://dicom-medical-imaging.region.amazonaws.com/datastore/datastore-id/studies/study-instance-uid/series/series-instance-uid/metadata ``` 1. Prepare and send your request. `GetDICOMSeriesMetadata` uses a HTTP GET request with [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) signing protocol. The following code example uses the `curl` command line tool to get metadata (`.json` file) from HealthImaging. ------ #### [ Shell ] ``` curl --request GET \ 'https://dicom-medical-imaging.us-east-1.amazonaws.com/datastore/d9a2a515ab294163a2d2f4069eed584c/studies/1.3.6.1.4.1.5962.1.2.4.20040826285059.5457/series/1.3.6.1.4.1.5962.1.3.4.1.20040825185059.5457/metadata \ --aws-sigv4 'aws:amz:us-east-1:medical-imaging' \ --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \ --header "x-amz-security-token:$AWS_SESSION_TOKEN" \ --header 'Accept: application/dicom+json' \ --output 'series-metadata.json' ``` ------ With the optional `imageSetId` parameter. ------ #### [ Shell ] ``` curl --request GET \ 'https://dicom-medical-imaging.us-east-1.amazonaws.com/datastore/d9a2a515ab294163a2d2f4069eed584c/studies/1.3.6.1.4.1.5962.1.2.4.20040826285059.5457/series/1.3.6.1.4.1.5962.1.3.4.1.20040825185059.5457/metadata?imageSetId=459e50687f121185f747b67bb60d1bc8' \ --aws-sigv4 'aws:amz:us-east-1:medical-imaging' \ --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \ --header "x-amz-security-token:$AWS_SESSION_TOKEN" \ --header 'Accept: application/dicom+json' \ --output 'series-metadata.json' ``` ------ **Note** The `imageSetId` parameter is required to retrieve series metadata for non-primary image sets. The `GetDICOMInstanceMetadata` action will only return series metadata for primary image sets if the `datastoreId`, `studyInstanceUID`, `seriesInstanceUID` are specified (without an `imagesetID`). # Getting DICOM instance frames from HealthImaging Use the `GetDICOMInstanceFrames` action to retrieve single or batch image frames (`multipart` request) from a DICOM instance in a HealthImaging [data store](getting-started-concepts.md#concept-data-store) by specifying the Series UID, Study UID, Instance UIDs, and frame numbers associated with a resource. You can specify the [image set](getting-started-concepts.md#concept-image-set) from which instance frames should be retrieved by providing the image set ID as a query parameter. The API will only return instance frames from primary image sets unless the optional [image set](getting-started-concepts.md#concept-image-set) parameter is provided. You can retrieve any instance frame (from primary or non-primary image sets) in the data store by specifying the `imageSetId` as a query parameter. DICOM data can be retrieved in either its stored transfer syntax or as uncompressed (ELE) format. **To get DICOM instance frames (`multipart`)** 1. Collect HealthImaging `datastoreId` and `imageSetId` parameter values. 1. Use the [https://docs.aws.amazon.com/healthimaging/latest/APIReference/API_GetImageSetMetadata.html](https://docs.aws.amazon.com/healthimaging/latest/APIReference/API_GetImageSetMetadata.html) action with the `datastoreId` and `imageSetId` parameter values to retrieve associated metadata values for `studyInstanceUID`, `seriesInstanceUID`, and `sopInstanceUID`. For more information, see [Getting image set metadata](get-image-set-metadata.md). 1. Determine the image frames to retrieve from the associated metadata to form the `frameList` parameter. The `frameList` parameter is a comma-separated list of one or more non-duplicate frame numbers, in any order. For example, the first image frame in the metadata will be frame 1. + Single-frame request: `/frames/1` + Multi-frame request: `/frames/1,2,3,4` 1. Construct a URL for the request using the values for `datastoreId`, `studyInstanceUID`, `seriesInstanceUID`, `sopInstanceUID`, `imageSetId`, and `frameList`. To view the entire URL path in the following example, scroll over the **Copy** button. The URL is of the form: ``` GET https://dicom-medical-imaging.region.amazonaws.com/datastore/datastore-id/studies/study-instance-uid/series/series-instance-uid/instances/sop-instance-uid/frames/1?imageSetId=image-set-id ``` 1. Prepare and send your request. `GetDICOMInstanceFrames` uses a HTTP GET request with [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) signing protocol. The following code example uses the `curl` command line tool to get image frames in a `multipart` response from HealthImaging. ------ #### [ Shell ] ``` curl --request GET \ 'https://dicom-medical-imaging.us-east-1.amazonaws.com/datastore/d9a2a515ab294163a2d2f4069eed584c/studies/1.3.6.1.4.1.5962.1.2.4.20040826285059.5457/series/1.3.6.1.4.1.5962.1.3.4.1.20040825185059.5457/instances/1.3.6.1.4.1.5962.1.1.4.1.1.20040826186059.5457/frames/1?imageSetId=459e50687f121185f747b67bb60d1bc8' \ --aws-sigv4 'aws:amz:us-east-1:medical-imaging' \ --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \ --header "x-amz-security-token:$AWS_SESSION_TOKEN" \ --header 'Accept: multipart/related; type=application/octet-stream; transfer-syntax=1.2.840.10008.1.2.1' ``` ------ **Note** The `transfer-syntax` UID is optional and defaults to Explicit VR Little Endian if not included. If transcoding to ELE is not feasible (due to import with warning) then pixels will be returned without transcoding. Supported transfer syntaxes include: Explicit VR Little Endian (ELE) - `1.2.840.10008.1.2.1` (default for lossless image frames) If `transfer-syntax=*` then the image frame(s) will be returned in the stored transfer syntax. High-Throughput JPEG 2000 with RPCL Options Image Compression (Lossless Only) - `1.2.840.10008.1.2.4.202` - if the instance is stored in HealthImaging as `1.2.840.10008.1.2.4.202` JPEG 2000 Lossless - `1.2.840.10008.1.2.4.90` - if the instance is stored in HealthImaging as lossless. JPEG Baseline (Process 1): Default Transfer Syntax for Lossy JPEG 8-bit Image Compression - `1.2.840.10008.1.2.4.50` - if the instance is stored in HealthImaging as `1.2.840.10008.1.2.4.50` JPEG 2000 Image Compression - `1.2.840.10008.1.2.4.91` - if the instance is stored in HealthImaging as `1.2.840.10008.1.2.4.91` High-Throughput JPEG 2000 Image Compression - `1.2.840.10008.1.2.4.203` - if the instance is stored in HealthImaging as `1.2.840.10008.1.2.4.203` JPEG XL Image Compression - `1.2.840.10008.1.2.4.112` - if the instance is stored in HealthImaging as `1.2.840.10008.1.2.4.112` Instances stored in HealthImaging with one or more image frames encoded in the MPEG family of [Transfer Syntaxes](supported-transfer-syntaxes.md) (which includes MPEG2, MPEG-4 AVC/H.264 and HEVC/H.265) may be retrieved with the corresponding transfer-syntax UID. For example, `1.2.840.10008.1.2.4.100` if the instance is stored as MPEG2 Main Profile Main Level. You may receive a 406 `NotAcceptableException` if the requested transfer syntax cannot be returned based on the stored transfer syntax, or if there are specific processing warnings for the instance. If this occurs, retry the call with `transfer-syntax=*`. For more information, see [Supported transfer syntaxes](supported-transfer-syntaxes.md) and [Image frame decoding libraries for AWS HealthImaging](reference-libraries.md). # Getting DICOM bulkdata from HealthImaging Use the `GetDICOMBulkdata` action to retrieve binary data that has been separated from DICOM metadata in a HealthImaging data store. When retrieving instance or series metadata, binary attributes larger than 1MB will be represented by a `BulkDataURI` instead of inline values. You can retrieve the binary data for any primary image set in the HealthImaging data store by using the `BulkDataURI` provided in the metadata response. You can retrieve bulkdata for non-Primary image sets by providing the image set ID as a query parameter. **To get DICOM bulkdata** When you retrieve DICOM metadata from a HealthImaging DICOMweb WADO-RS action, such as `GetDICOMInstanceMetadata` or `GetDICOMSeriesMetadata`, large binary attributes will be replaced in-line with BulkDataURIs, as shown below: ``` "00451026": { "vr": "UN", "BulkDataURI": "https://dicom-medical-imaging.us-west-2.amazonaws.com/datastore//studies//series//instances//bulkdata/" } ``` To retrieve a DICOM element with the `GetDICOMBulkdata` action, use the following steps. 1. Construct a URL for the request using the values from the `BulkDataURI`, of the form: ``` https://dicom-medical-imaging.region.amazonaws.com/datastore/datastore-id/studies/study-instance-uid/series/series-instance-uid/instances/sop-instance-uid/bulkdata/bulkdata-uri-hash ``` 1. Issue your `GetDICOMBulkdata` command as an HTTP GET request with [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) signing protocol. The following code example uses the `curl` command line tool to retrieve a DICOM element from a primary image set: ``` curl --request GET \ 'https://dicom-medical-imaging.us-east-1.amazonaws.com/datastore/d9a2a515ab294163a2d2f4069eed584c/studies/1.3.6.1.4.1.5962.1.2.4.20040826285059.5457/series/1.3.6.1.4.1.5962.1.3.4.1.20040825185059.5457/instances/1.2.840.10008.5.1.4.1.1.7/bulkdata/b026324c6904b2a9cb4b88d6d61c81d1' \ --aws-sigv4 'aws:amz:us-east-1:medical-imaging' \ --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \ --header "x-amz-security-token:$AWS_SESSION_TOKEN" \ --header 'Accept: application/octet-stream' \ --output 'bulkdata.bin' ``` To retrieve a DICOM data element from a non-primary image set, supply an `ImageSetId` parameter: ``` curl --request GET \ 'https://dicom-medical-imaging.us-east-1.amazonaws.com/datastore/d9a2a515ab294163a2d2f4069eed584c/studies/1.3.6.1.4.1.5962.1.2.4.20040826285059.5457/series/1.3.6.1.4.1.5962.1.3.4.1.20040825185059.5457/instances/1.2.840.10008.5.1.4.1.1.7/bulkdata/b026324c6904b2a9cb4b88d6d61c81d1?imageSetId=459e50687f121185f747b67bb60d1bc8' \ --aws-sigv4 'aws:amz:us-east-1:medical-imaging' \ --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \ --header "x-amz-security-token:$AWS_SESSION_TOKEN" \ --header 'Accept: application/octet-stream' \ --output 'bulkdata.bin' ``` **Note** The `imageSetId` parameter is required to retrieve bulkdata for non-primary image sets. The GetDICOMBulkdata action will only return bulkdata for primary image sets if the `datastoreId`, `studyInstanceUID`, `seriesInstanceUID`, and `SOPInstanceUID` are specified (without an `imagesetID`).