6.7 QIDO-RS Request/Response
Prev | 6 Data Communication Requirements | Next

## 6.7 QIDO-RS Request/Response

DICOM QIDO-RS defines several action types. An implementation shall support the following action types:

1. SearchForStudies

   This action searches for DICOM Studies that match specified search parameters and returns a list of matching studies and the requested attributes for each study.

2. SearchForSeries

   This action searches for DICOM Series that match specified search parameters and returns a list of matching series and the requested attributes for each series.

3. SearchForInstances

   This action searches for DICOM Instances that match specified search parameters and returns a list of matching instances and the requested attributes for each instance.

### 6.7.1 QIDO-RS - Search

#### 6.7.1.1 Request

The specific resources to be used for the search actions shall be as follows:

- Resource

  - SearchForStudies

    - {+SERVICE}/studies{?query*,fuzzymatching,limit,offset}

  - SearchForSeries

    - {+SERVICE}/studies/{StudyInstanceUID}/series{?query*,fuzzymatching,limit,offset}

    - {+SERVICE}/series{?query*,fuzzymatching,limit,offset}

  - SearchForInstances

    - {+SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances{?query*,fuzzymatching,limit,offset}

    - {+SERVICE}/studies/{StudyInstanceUID}/instances{?query*,fuzzymatching,limit,offset}

    - {+SERVICE}/instances{?query*,fuzzymatching,limit,offset}

  where

  - {+SERVICE} is the base URL for the QIDO RESTful service. This may be a combination of protocol (http or https), authority, and path.

  - {StudyInstanceUID} is the unique Study Instance UID for a single study.

  - {SeriesInstanceUID} is the unique Series Instance UID for a single series.

- Method

  - GET

- Headers

  - Accept - The Media Type of the query results. The types allowed for this request header are:

    - multipart/related; type=application/dicom+xml (default)

      Specifies that the results should be DICOM PS3.19 XML (one part per result)

    - application/json

      Specifies that the results should be DICOM JSON

    A QIDO-RS provider shall support both Accept header values

  - Cache-control: no-cache (recommended)

    If included, specifies that search results returned should be current and not cached.

- {query}

  - {attributeID}={value}

    0-n / {attributeID}={value} pairs allowed

  - includefield={attributeID} | all

    0-n includefield / {attributeID} pairs allowed, where "all" indicates that all available attributes should be included for each response.

  Each {attributeID} must refer to one of:

  - Patient IE attributes

  - Study IE attributes

  - Series IE attributes (SearchForSeries or SearchForInstances requests only)

  - Composite Instance IE attributes (SearchForInstances requests only)

  - Additional Query/Retrieve Attributes (Section C.3.4 in PS3.4 )

  - Timezone Offset From UTC (0008,0201)

  See Section 6.7.1.1.1 for {attributeID} and {value} encoding rules

- fuzzymatching=true | false

- limit={maximumResults}

- offset={skippedResults}

##### 6.7.1.1.1 {attributeID} encoding rules

Each {attributeID} query key shall be unique unless the associated DICOM Attribute allows UID List matching (see Section C.2.2.2.2 in PS3.4 ), in which case each {value} will be interpreted to be an element of the UID List.

The acceptable values for {value} are determined by the types of matching allowed by C-FIND for its associated {attributeID} (see Section C.2.2.2 in PS3.4 ). All characters in {value} that are disallowed for URIs shall be percent-encoded. See IETF RFC 3986 for details.

If an {attributeID} is passed as the value of an "includefield" query key this is equivalent to C-FIND Universal matching for the specified attribute (see Section C.2.2.2.3 in PS3.4 ).

{attributeID} can be one of the following:

- {dicomTag}

- {dicomKeyword}

- {dicomTag}.{attributeID}, where {attributeID} is an element of the sequence specified by {dicomTag}

- {dicomKeyword}.{attributeID}, where {attributeID} is an element of the sequence specified by {dicomKeyword}

{dicomTag} is the eight character hexadecimal string corresponding to the Tag of a DICOM Attribute (see Chapter 6 in PS3.6 ).

{dicomKeyword} is the Keyword of a DICOM Attribute (see Chapter 6 in PS3.6 ).

### Note

Examples of valid values for {attributeID}:

- 0020000D

- StudyInstanceUID

- 00101002.00100020

- OtherPatientIDsSequence.PatientID

- 00101002.00100024.00400032

- OtherPatientIDsSequence.IssuerOfPatientIDQualifiersSequence.UniversalEntityID

### Note

Examples of valid QIDO-RS URLs:

- http://dicomrs/studies​?PatientID=11235813

- http://dicomrs/studies​?PatientID=11235813​&StudyDate=20130509

- http://dicomrs/studies​?00100010=SMITH*​&00101002.00100020=11235813​&limit=25

- http://dicomrs/studies​?00100010=SMITH*​&OtherPatientIDsSequence.00100020=11235813

- http://dicomrs/studies​?PatientID=11235813​&includefield=00081048​&includefield=00081049​&includefield=00081060

- http://dicomrs/studies​?PatientID=11235813​&StudyDate=20130509-20130510

- http://dicomrs/studies​?StudyInstanceUID=1.2.392.200036.9116.2.2.2.2162893313.1029997326.94587​%2c1.2.392.200036.9116.2.2.2.2162893313.1029997326.94583

#### 6.7.1.2 Response

The Server shall perform the query indicated in the request. The Server shall return the query results or, when the query cannot be performed, an error code.

If the limit query key is not specified or its value exceeds the total number of matching results then {maximumResults} is the lesser of the number of matching results and the maximum number of results supported by the Server.

If the offset query key is not specified or its value is less than zero then {skippedResults} is zero.

The first result returned shall be result number ({skippedResults} + 1). The last result returned shall be result number ({skippedResults} + {maximumResults}). If ({skippedResults} + 1) exceeds {maximumResults} then no results are returned.

If the number of results exceeds the maximum supported by the server, the server shall return the maximum supported results and the response shall include the following HTTP/1.1 Warning header (see RFC 7230 Section 14.46):

`Warning: 299 {SERVICE}: "The number of results exceeded the maximum supported by the server. Additional results can be requested.`

### Note

The client can request additional results by specifying a value for the "offset" query key.

The server shall be idempotent so that if the list of results is the same, the response to a request with a specific set of parameters shall always be the same, including order. If the complete list of results is different for subsequent transactions the responses may be different. In a situation where results are changing due to changes in the server contents, queries using the limit and offset may be inconsistent.

The response format depends on the Accept header specified in the request.

##### 6.7.1.2.1 Matching

The matching semantics for each attribute are determined by the types of matching allowed by C-FIND (see Section C.2.2.2 in PS3.4 ).

Matching results shall be generated according to the Hierarchical Search Method described in Section C.4.1.3.1.1 in PS3.4 .

Combined Datetime matching shall be performed (see Section C.2.2.2.5 in PS3.4 ).

### Note

If a QIDO-RS provider is acting as a proxy for a C-FIND SCP that does not support combined Datetime matching the QIDO-RS provider will need to perform a C-FIND request using Date only and filter results outside the time range before returning a QIDO-RS response

If the TimezoneOffsetFromUTC / 00080201 query key is included in the request, dates and times in the request are to be interpreted in the specified time zone.

If the "fuzzymatching=true" query key/value is included in the request and it is supported then additional fuzzy semantic matching of person names shall be performed in the manner specified in the DICOM Conformance Statement for the service provider.

If the "fuzzymatching=true" query key/value is included in the request and it is not supported, the response shall include the following HTTP/1.1 Warning header (see RFC 7230 Section 14.46):

Warning: 299 {SERVICE}: "The fuzzymatching parameter is not supported. Only literal matching has been performed."

where {SERVICE} is the base URL for the QIDO-RS provider. This may be a combination of scheme (http or https), host, port, and application.

### Note

The Warning header is separate from the Status Line and does not affect the returned Status Code.

###### 6.7.1.2.1.1 Study Matching

Providers of the SearchForStudies service shall support the search query keys described in Table 6.7.1-1:

Table 6.7.1-1. QIDO-RS STUDY Search Query Keys

Key Word | Tag
--- | ---
StudyDate | 00080020
StudyTime | 00080030
AccessionNumber | 00080050
ModalitiesInStudy | 00080061
ReferringPhysicianName | 00080090
PatientName | 00100010
PatientID | 00100020
StudyInstanceUID | 0020000D
StudyID | 00200010

###### 6.7.1.2.1.2 Series Matching

Providers of the SearchForSeries service shall support the search query keys described in Table 6.7.1-1a:

Table 6.7.1-1a. QIDO-RS SERIES Search Query Keys

Key Word | Tag
--- | ---
Modality | 00080060
SeriesInstanceUID | 0020000E
SeriesNumber | 00200011
PerformedProcedureStepStartDate | 00400244
PerformedProcedureStepStartTime | 00400245
RequestAttributeSequence | 00400275
>ScheduledProcedureStepID | 00400009
>RequestedProcedureID | 00401001

If {StudyInstanceUID} is not specified in the URL and this form of Relational Query is supported, all Study-level attributes specified in Table 6.7.1-1 shall also be supported.

###### 6.7.1.2.1.3 Instance Matching

Providers of the SearchForInstances service shall support the search query keys described in Table 6.7.1-1b:

Table 6.7.1-1b. QIDO-RS INSTANCE Search Query Keys

Key Word | Tag
--- | ---
SOPClassUID | 00080016
SOPInstanceUID | 00080018
InstanceNumber | 00200013

If {StudyInstanceUID} is not specified in the URL and this form of Relational Query is supported, all Study-level attributes specified in Table 6.7.1-1 shall also be supported.

If {SeriesInstanceUID} is not specified in the URL and this form of Relational Query is supported, all Series-level attributes specified in Table 6.7.1-1a shall also be supported.

##### 6.7.1.2.2 Query Result Attributes

###### 6.7.1.2.2.1 Study Result Attributes

For each matching Study, the QIDO-RS provider shall return all attributes in accordance with Table 6.7.1-2:

Table 6.7.1-2. QIDO-RS STUDY Returned Attributes

Attribute Name | Tag | Notes
--- | --- | ---
Specific Character Set | (0008,0005) | If necessary for encoding any returned attributes
Study Date | (0008,0020) |
Study Time | (0008,0030) |
Accession Number | (0008,0050) |
Instance Availability | (0008,0056) |
Modalities in Study | (0008,0061) |
Referring Physician's Name | (0008,0090) |
Timezone Offset From UTC | (0008,0201) | May be absent if no value is available
Retrieve URL | (0008,1190) | Shall be empty if the resource cannot be retrieved via WADO-RS ### Note The VR of this attribute has changed from UT to UR.
Patient's Name | (0010,0010) |
Patient ID | (0010,0020) |
Patient's Birth Date | (0010,0030) |
Patient's Sex | (0010,0040) |
Study Instance UID | (0020,000D) |
Study ID | (0020,0010) |
Number of Study Related Series | (0020,1206) |
Number of Study Related Instances | (0020,1208) |
All other Study Level DICOM Attributes passed as {attributeID} query keys that are supported by the service provider as matching or return attributes
All other Study Level DICOM Attributes passed as "includefield" query values that are supported by the service provider as return attributes
All available Study Level DICOM Attributes if the "includefield" query key is included with a value of "all"

Series Level and Instance Level attributes passed as "includefield" query values shall not be returned.

### Note

The above list is consistent with those required for IHE RAD-14 (see http://www.ihe.net/Technical_Framework/upload/IHE_RAD_TF_Vol2.pdf Table 4.14-1).

###### 6.7.1.2.2.2 Series Result Attributes

For each matching Series, the QIDO-RS provider shall return all attributes listed in Table 6.7.1-2a:

Table 6.7.1-2a. QIDO-RS SERIES Returned Attributes

Attribute Name | Tag | Notes
--- | --- | ---
Specific Character Set | (0008,0005) | If necessary for encoding any returned attributes
Modality | (0008,0060) |
Timezone Offset From UTC | (0008,0201) | May be absent if no value is available
Series Description | (0008,103E) | May be absent if no value is available
Retrieve URL | (0008,1190) | Shall be empty if the resource cannot be retrieved via WADO-RS ### Note The VR of this attribute has changed from UT to UR.
Series Instance UID | (0020,000E) |
Series Number | (0020,0011) |
Number of Series Related Instances | (0020,1209) |
Performed Procedure Step Start Date | (0040,0244) | May be absent if no value is available
Performed Procedure Step Start Time | (0040,0245) | May be absent if no value is available
Request Attribute Sequence | (0040,0275) | May be absent if no value is available
>Scheduled Procedure Step ID | (0040,0009) |
>Requested Procedure ID | (0040,1001) |
All other Series Level DICOM Attributes passed as {attributeID} query keys that are supported by the service provider as matching or return attributes
All other Study or Series Level DICOM Attributes passed as "includefield" query values that are supported by the service provider as return attributes
All available Instance Level DICOM Attributes if the "includefield" query key is included with a value of "all"
If {StudyInstanceUID} is not specified, all Study-level attributes specified in Table 6.7.1-2

Instance Level attributes passed as "includefield" query values shall not be returned.

### Note

The above list is consistent with the attributes required for IHE RAD-14 (see http://www.ihe.net/Technical_Framework/upload/IHE_RAD_TF_Vol2.pdf Table 4.14-1).

###### 6.7.1.2.2.3 Instance Result Attributes

For each matching instance, the QIDO-RS provider shall return all attributes listed in Table 6.7.1-2b:

Table 6.7.1-2b. QIDO-RS INSTANCE Returned Attributes

Attribute Name | Tag | Notes
--- | --- | ---
Specific Character Set | (0008,0005) | If necessary for encoding any returned attributes
SOP Class UID | (0008,0016) |
SOP Instance UID | (0008,0018) |
Instance Availability | (0008,0056) |
Timezone Offset From UTC | (0008,0201) | May be absent if no value is available
Retrieve URL | (0008,1190) | Shall be empty if the resource cannot be retrieved via WADO-RS ### Note The VR of this attribute has changed from UT to UR.
Instance Number | (0020,0013) |
Rows | (0028,0010) | Only present for Image Instances
Columns | (0028,0011) | Only present for Image Instances
Bits Allocated | (0028,0100) | Only present for Image Instances
Number of Frames | (0028,0008) | Only present for Multi-frame image instances
All other Instance Level DICOM Attributes passed as {attributeID} query keys that are supported by the service provider as matching or return attributes
All other Study, Series or Instance Level DICOM Attributes passed as "includefield" query values that are supported by the service provider as return attributes
All available Instance Level DICOM Attributes if the "includefield" query key is included with a value of "all"
If {StudyInstanceUID} is not specified, all Study-level attributes specified in Table 6.7.1-2
If {SeriesInstanceUID} is not specified, all Series-level attributes specified in Table 6.7.1-2a

### Note

The above list is consistent with the attributes required for IHE RAD-14 (see http://www.ihe.net/Technical_Framework/upload/IHE_RAD_TF_Vol2.pdf Table 4.14-1 and Table 4.14-2).

##### 6.7.1.2.3 Query Result Messages

The server shall support returning query results as:

- XML Results

- JSON Results

The result format used shall depend on the Accept header of the request.

###### 6.7.1.2.3.1 XML Results

- Content-Type: multipart/related; type=application/dicom+xml

  - The response is a multipart message body where each part is a DICOM PS3.19 XML NativeDicomModel element containing the attributes for one matching Study, Series or Instance (see Section A.1 in PS3.19 ).

  - The provider of the QIDO service may use a BulkData reference at its discretion (see Table A.1.5-2 in PS3.19 and Section 6.5.6). For example, this might be done to avoid encoding a large DICOM Value Field, such as an image thumbnail.

  - If there are no matching results, the message body will be empty.

- Each item in the multipart response will contain the following HTTP/1.1 headers:

  - Content-Type: application/dicom+xml

###### 6.7.1.2.3.2 JSON Results

- Content-Type: application/json

  - The response is a DICOM JSON message containing a DICOM JSON property for each matching study, series or instance containing sub-properties describing the matching attributes for each study, series or instance (see Section F.2).

  - The provider of the QIDO service may use a BulkDataURI reference at its discretion (see Section F.2.6). For example, this might be done to avoid encoding a large DICOM Value Field, such as an image thumbnail.

  - If there are no matching results, the JSON message is empty.

#### 6.7.1.3 Status Codes

Table 6.7-1 lists the HTTP/1.1 status codes that shall be used to report any of the associated error and warning situations. Other error codes may be present for other error and warning situations.

Table 6.7-1. QIDO-RS HTTP/1.1 Status Codes

Code | Name | Description
--- | --- | ---
Success
200 | OK | The query completed and any matching results are returned in the message body.
Failure
400 | Bad Request | The QIDO-RS Provider was unable to perform the query because the Service Provider cannot understand the query component.
401 | Unauthorized | The QIDO-RS Provider refused to perform the query because the client is not authenticated.
403 | Forbidden | The QIDO-RS Provider understood the request, but is refusing to perform the query (e.g., an authenticated user with insufficient privileges).
413 | Request entity too large | The query was too broad and a narrower query or paging should be requested. The use of this status code should be documented in the conformance statement.
503 | Busy | Service is unavailable.

Prev | Up | Next
6.6 STOW-RS Request/Response | Home | 6.8 RS Capabilities Service