View a markdown version of this page

Searching DICOM data in HealthImaging - AWS HealthImaging
DICOMweb search APIs for HealthImagingSupported DICOMweb query types for HealthImagingUsing IncludeField in QIDO-RS queries

Searching DICOM data in HealthImaging

AWS HealthImaging offers representations of DICOMweb QIDO-RS APIs to search for studies, series, and instances by Patient ID, and receive their unique identifiers for further usage. HealthImaging's DICOMweb QIDO-RS APIs offer flexibility in how you search for data stored in HealthImaging and provide interoperability with legacy applications.

Important

HealthImaging's DICOMweb APIs can be used to return image set information with QIDO-RS. HealthImaging DICOMweb APIs reference only primary image sets unless otherwise noted. Use HealthImaging cloud native actions, or the optional image set parameter of DICOMweb actions to retrieve non-primary image sets. HealthImaging's DICOMweb APIs can be used to return image set information with DICOMweb-conformant responses.

HealthImaging DICOMweb QIDO-RS actions can return a maximum of 10,000 records. In the case that more than 10,000 resources exist, they will not be retrievable via the QIDO-RS actions, but may be retrieved via DICOMweb WADO-RS actions or cloud native actions.

The APIs listed in this section are built in conformance to the DICOMweb (QIDO-RS) standard for web-based medical imaging. They are not offered through AWS CLI and AWS SDKs.

DICOMweb search APIs for HealthImaging

The following table describes all HealthImaging representations of DICOMweb QIDO-RS APIs available for searching data in HealthImaging.

HealthImaging representations of DICOMweb QIDO-RS APIs
Name Description
SearchDICOMStudies Search for DICOM studies in HealthImaging by specifying search query elements using a GET request. Study search results are returned in JSON format, ordered by last update, date descending (latest to oldest). See Search for studies.
SearchDICOMSeries Search for DICOM series in HealthImaging by specifying search query elements using a GET request. Series search results are returned in JSON format, ordered by Series Number (0020, 0011) in ascending order (oldest to latest). See Search for series.
SearchDICOMInstances Search for DICOM instances in HealthImaging by specifying search query elements using a GET request. Instance search results are returned in JSON format, ordered by Instance Number (0020, 0013) in ascending order (oldest to latest). See Search for instances.

Supported DICOMweb query types for HealthImaging

HealthImaging supports QIDO-RS hierarchical resource queries at the Study, Series, and SOP Instance levels. When using QIDO-RS hierarchical search for HealthImaging:

  • Searching for studies returns a list of Studies

  • Searching for a Study’s Series requires a known StudyInstanceUID and returns a list of Series

  • Searching a list of Instances requires a known StudyInstanceUID and SeriesInstanceUID

The following table describes supported QIDO-RS hierarchical query types for searching data in HealthImaging.

HealthImaging supported QIDO-RS query types
Query type Example
Attribute value queries

Search for all series in a Study where modality=CT.

.../studies/1.3.6.1.4.1.14519.5.2.1.6279.6001.101370605276577556143013894866/series?00080060=CT

Search all studies where patient ID and study date are these values, respectively.

…/studies?PatientID=11235813&StudyDate=20130509
Keyword queries

Search all series using the SeriesInstanceUID keyword.

.../studies/1.3.6.1.4.1.14519.5.2.1.6279.6001.101370605276577556143013894866/series?SeriesInstanceUID=1.3.6.1.4.1.14519.5.2.1.6279.6001.101370605276577556143013894868
Tag queries

Search for tags using query parameters passed in group/element form.

{group}{element} like 0020000D
Range queries

...?Modality=CT&StudyDate=AABBYYYY-BBCCYYYY
Result paging with limit and offset

.../studies?limit=1&offset=0&00080020=20000101

You can use the limit and offset parameters to paginate search responses. The default value of limit is 1000, and see AWS HealthImaging endpoints and quotas for the maximum value.

Max limit = 1000, Max offset = 9000
Wildcard queries

Wildcard queries provide more flexibility on search using "*" and "?". "*" matches any sequence of characters (including a zero length value) and "?" matches any single character.

Search for all studies in a datastore where StudyDescription contains "Nuclear":

.../studies?StudyDescription=*Nuclear*

Search for all studies where StudyDescription ends with "Nuclear":

.../studies?StudyDescription=*Nuclear

Search for all studies where StudyDescription starts with "Nuclear":

.../studies?StudyDescription=Nuclear*

Search for all studies where PatientID has exactly any 3 characters after 200965981:

.../studies?PatientID=200965981???
FuzzyMatching queries

Enable fuzzy matching on name DICOM attributes (PatientName (0010,0010), ReferringPhysicianName(0008,0090)) by adding the fuzzymatching optional query parameter:

.../studies?fuzzymatching=true&PatientName="Thomas^Albert"

This query performs case-insensitive prefix word matching on any part of the PatientName value. It returns results with PatientName values like "thomas", "Albert", "Thomas Albert", "Thomas^Albert", but not "hom" or "ber".
IncludeField queries

Use the includefield query parameter to request additional DICOM attributes beyond the default response set.

Return specific attributes by tag:

.../studies?PatientID=11235813&includefield=00101081&includefield=PatientWeight

Return all available attributes:

.../studies?PatientID=11235813&includefield=all

Return sequence (SQ) sub-attributes using dotted notation:

.../studies?PatientID=11235813&includefield=00080096.00080100

Return private data elements:

.../instances?includefield=00191001&00190010=Philips

Using IncludeField in QIDO-RS queries

The includefield query parameter lets you request additional DICOM attributes beyond the default response set in HealthImaging QIDO-RS queries. You can use includefield at the study, series, and instance levels.

Syntax

Use the following GET request format to include additional fields in your QIDO-RS queries:

GET .../studies?<query_params>&includefield=<tag_or_keyword>
GET .../studies/<StudyInstanceUID>/series?<query_params>&includefield=<tag_or_keyword>
GET .../studies/<StudyInstanceUID>/series/<SeriesInstanceUID>/instances?<query_params>&includefield=<tag_or_keyword>

You can specify multiple includefield parameters in a single request:

GET .../studies?PatientID=11235813&includefield=00101081&includefield=00101030&includefield=00101010

Supported values for includefield

The following table describes the supported values for the includefield parameter.

Supported includefield values
Value type Description Example
DICOM tag (8 hex characters) Request a specific DICOM attribute by its tag in GGGGEEEE format. includefield=00081030
all Request all available DICOM attributes for the resource level. includefield=all
Dotted SQ path Request a specific sub-attribute within a Sequence (SQ) attribute using dot notation: <parent_tag>.<child_tag>. includefield=00080096.00080100
Private data element tag Request a private tag (odd-group element). Requires the privateCreatorElement parameter. includefield=00191001
Standard DICOM attributes including bulkdata Request specific single or multiple attributes by tag or keyword. includefield=00102201

Behavior and rules

The following rules apply to includefield queries:

  • Default response – Without includefield, the QIDO-RS response returns only the standard set of attributes.

  • includefield=all – Returns all available attributes at the requested level. When all is combined with other includefield values, all takes priority.

  • Maximum tags – A request can include up to 50 includefield parameters.

  • Duplicate tags – Duplicate includefield values are deduplicated and treated as a single request.

  • Invalid or missing tags – If a requested tag does not exist in the DICOM data or is invalid, it is silently omitted from the response. Other valid includefield attributes are still returned.

Sequence (SQ) attributes

Use dot notation to request nested attributes within a Sequence (SQ) attribute:

includefield=<parent_SQ_tag>.<child_tag>

For example, to retrieve CodeValue (0008,0100) within ReferringPhysicianIdentificationSequence (0008,0096):

GET .../studies?PatientID=11235813&includefield=00080096.00080100

Multi-level nesting is supported. For example:

includefield=00081115.00081199.00081150

Private tags

Private DICOM data elements (odd-group tags) are supported at all resource levels. To request private tags, include the privateCreatorElement query parameter.

Use the following syntax:

GET .../instances?includefield=<private_tag>&<creator_tag>=<creator_name>

For example:

GET .../instances?includefield=00191001&00190010=Philips

The following rules apply to private tags:

  • The privateCreatorElement tag and creator name must be provided as a match parameter if the private tag is requested.

  • If the specified privateCreatorElement is not found, the private tag is silently omitted.

  • Requesting only a privateCreatorElement tag without a private data element returns the creator element name and value only. It does not return all tags belonging to that creator's block.

Bulkdata tags

DICOM attributes with bulkdata VRs (OB, OD, OF, OL, UN, OW, OV) with binary value greater than 1 MB requested as part of the includefield are returned as bulkdataURI instead of the raw binary value. For more information about retrieving bulkdata, see Retrieving DICOM bulkdata in HealthImaging.

What does includefield=all return at each level?

When includefield=all is specified, the response includes all attributes at the specific resource level.

Study level (includefield=all)

The following table lists all attributes returned at the study level when includefield=all is specified.

Study level attributes for includefield=all
Tag Name VR
00080005SpecificCharacterSetCS
00080020StudyDateDA
00080030StudyTimeTM
00080050AccessionNumberSH
00080051IssuerOfAccessionNumberSequenceSQ
00080056InstanceAvailabilityCS
00080061ModalitiesInStudyCS
00080062SOPClassesInStudyUI
00080090ReferringPhysicianNamePN
0008009CConsultingPhysicianNamePN
00080201TimezoneOffsetFromUTCSH
00081030StudyDescriptionLO
00081048PhysiciansOfRecordPN
00081060NameOfPhysiciansReadingStudyPN
00081080AdmittingDiagnosesDescriptionLO
00081190RetrieveURLUR
00100010PatientNamePN
00100020PatientIDLO
00100021IssuerOfPatientIDLO
00100022TypeOfPatientIDCS
00100026SourcePatientGroupIdentificationSequenceSQ
00100027GroupOfPatientsIdentificationSequenceSQ
00100028SubjectRelativePositionInImageUS
00100030PatientBirthDateDA
00100032PatientBirthTimeTM
00100033PatientBirthDateInAlternativeCalendarLO
00100034PatientDeathDateInAlternativeCalendarLO
00100035PatientAlternativeCalendarCS
00100040PatientSexCS
00100050PatientInsurancePlanCodeSequenceSQ
00100101PatientPrimaryLanguageCodeSequenceSQ
00100102PatientPrimaryLanguageModifierCodeSequenceSQ
00100200QualityControlSubjectCS
00100201QualityControlSubjectTypeCodeSequenceSQ
00100213StrainNomenclatureLO
00100214StrainStockNumberLO
00100215StrainSourceRegistryCodeSequenceSQ
00100217StrainSourceLO
00100219StrainCodeSequenceSQ
00100223GeneticModificationsNomenclatureLO
00100229GeneticModificationsCodeSequenceSQ
00101001OtherPatientNamesPN
00101005PatientBirthNamePN
00101010PatientAgeAS
00101020PatientSizeDS
00101021PatientSizeCodeSequenceSQ
00101022PatientBodyMassIndexDS
00101023MeasuredAPDimensionDS
00101024MeasuredLateralDimensionDS
00101030PatientWeightDS
00101040PatientAddressLO
00101060PatientMotherBirthNamePN
00101080MilitaryRankLO
00101081BranchOfServiceLO
00102000MedicalAlertsLO
00102110AllergiesLO
00102150CountryOfResidenceLO
00102152RegionOfResidenceLO
00102154PatientTelephoneNumbersSH
00102160EthnicGroupSH
00102180OccupationSH
001021A0SmokingStatusCS
001021C0PregnancyStatusUS
001021D0LastMenstrualDateDA
001021F0PatientReligiousPreferenceLO
00102201PatientSpeciesDescriptionLO
00102202PatientSpeciesCodeSequenceSQ
00102203PatientSexNeuteredCS
00102210AnatomicalOrientationTypeCS
00102292PatientBreedDescriptionLO
00102293PatientBreedCodeSequenceSQ
00102295BreedRegistrationNumberLO
00102296BreedRegistryCodeSequenceSQ
00102297ResponsiblePersonPN
00102298ResponsiblePersonRoleCS
00102299ResponsibleOrganizationLO
00109431ExaminedBodyThicknessFL
0020000DStudyInstanceUIDUI
00200010StudyIDSH
00201206NumberOfStudyRelatedSeriesIS
00201208NumberOfStudyRelatedInstancesIS
00321032RequestingPhysicianPN
00321033RequestingServiceLO
00321060RequestedProcedureDescriptionLO
00321070RequestedContrastAgentLO
00380010AdmissionIDLO
00380016RouteOfAdmissionsLO
00380020AdmittingDateDA
00380021AdmittingTimeTM
00380050SpecialNeedsLO
00380060ServiceEpisodeIDLO
00380062ServiceEpisodeDescriptionLO
00380300CurrentPatientLocationLO
00380400PatientInstitutionResidenceLO
00380500PatientStateLO
00400244PerformedProcedureStepStartDateDA
00400245PerformedProcedureStepStartTimeTM
00400250PerformedProcedureStepEndDateDA
00400251PerformedProcedureStepEndTimeTM
00400253PerformedProcedureStepIDSH
00081032ProcedureCodeSequenceSQ
00100024IssuerOfPatientIDQualifiersSequenceSQ
00321034RequestingServiceCodeSequenceSQ
00321064RequestedProcedureCodeSequenceSQ
00401012ReasonForPerformedProcedureCodeSequenceSQ

Series level (includefield=all)

The following table lists the series-level attributes returned when includefield=all is specified. The series level also returns all study-level attributes listed in the preceding table.

Series level attributes for includefield=all
Tag Name VR
00080021SeriesDateDA
00080031SeriesTimeTM
00080060ModalityCS
00080064ConversionTypeCS
00080068PresentationIntentTypeCS
00080070ManufacturerLO
00080080InstitutionNameLO
00080082InstitutionCodeSequenceSQ
00081010StationNameSH
0008103ESeriesDescriptionLO
0008103FSeriesDescriptionCodeSequenceSQ
00081040InstitutionalDepartmentNameLO
00081041InstitutionalDepartmentTypeCodeSequenceSQ
00081050PerformingPhysicianNamePN
00081070OperatorsNamePN
00081090ManufacturerModelNameLO
00180010ContrastBolusAgentLO
00180015BodyPartExaminedCS
00180050SliceThicknessDS
00180088SpacingBetweenSlicesDS
00181000DeviceSerialNumberLO
00181016SecondaryCaptureDeviceManufacturerLO
00181018SecondaryCaptureDeviceManufacturerModelNameLO
00181019SecondaryCaptureDeviceSoftwareVersionsLO
00181020SoftwareVersionsLO
00181030ProtocolNameLO
00181050SpatialResolutionDS
00181200DateOfLastCalibrationDA
00181201TimeOfLastCalibrationTM
00185100PatientPositionCS
0020000DStudyInstanceUIDUI
0020000ESeriesInstanceUIDUI
00200011SeriesNumberIS
00200052FrameOfReferenceUIDUI
00200060LateralityCS
00201209NumberOfSeriesRelatedInstancesIS
00540081NumberOfSlicesUS
00540101NumberOfTimeSlicesUS
00541000SeriesTypeCS

Instance level (includefield=all)

At the instance level, includefield=all returns the full instance-level DICOM metadata. This includes all attributes stored in the instance metadata in HealthImaging storage. Every DICOM tag present in the original DICOM file for that instance is returned, except the pixel data attribute.

Topics