Page tree
Skip to end of metadata
Go to start of metadata

Contents:


Post A Search To The XNAT Search Engine

This REST endpoint assumes you have built a valid XML search. You can download the XML of any existing data table in XNAT and use that as a starting point, or you can build your own. See How to Query the XNAT Search Engine with REST API.

POST - /data/search

Parameters:

format

Optional querystring parameter. Specifies the format of the returned data

  • xml (default)
  • html
  • json
  • csv
bodyRequired search definition. Can be included in the body, or in a supplied XML file

Response: A valid search will return a formatted search result, showing data that the user has permission to see.

You can also create a stored search out of a valid XML search. See Stored Search API


Get A List Of Available Data Elements

This REST endpoint displays a list of all installed data types in your XNAT, regardless of whether there is available data of that type. 

GET - /data/search/elements

Parameters:

format

Optional querystring parameter. Specifies the format of the returned data

  • xml (default)
  • html
  • json
  • csv

Response:

Showing JSON formatted results. Note that the ELEMENT_NAME field corresponds with the XNAT xsiType for that data type.

{
  "ResultSet": {
    "Result": [
      {
        "SINGULAR": "Project",
        "SECURED": "true",
        "ELEMENT_NAME": "xnat:projectData",
        "COUNT": "10",
        "PLURAL": "Projects"
      },
      {
        "SINGULAR": "Subject",
        "SECURED": "true",
        "ELEMENT_NAME": "xnat:subjectData",
        "COUNT": "39",
        "PLURAL": "Subjects"
      },
      {
        "SINGULAR": "MR Session",
        "SECURED": "true",
        "ELEMENT_NAME": "xnat:mrSessionData",
        "COUNT": "36",
        "PLURAL": "MR Sessions"
      },
      {
        "SINGULAR": "PET Session",
        "SECURED": "true",
        "ELEMENT_NAME": "xnat:petSessionData",
        "COUNT": "7",
        "PLURAL": "PET Sessions"
      },
      ...
    ],
    "title": "Data-Types"
  }
}


Get A List Of Queryable Fields For A Given Data Type

From the list of available elements, supply an xsiType to get a list of columns you can search on.

GET - /data/search/elements/{xsiType}

Parameters

{xsiType}Required path parameter.
format

Optional querystring parameter. Specifies the format of the returned data

  • xml (default)
  • html
  • json
  • csv

Response

Displaying JSON-formatted result for a search on /data/search/elements/xnat:subjectData

 Show JSON Response
{
  "ResultSet": {
    "Result": [
      {
        "SUMMARY": "xnat:subjectData\/meta\/insert_date",
        "SRC": "0",
        "FIELD_ID": "INSERT_DATE",
        "HEADER": "Inserted",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "date",
        "DESC": "Inserted"
      },
      {
        "SUMMARY": "xnat:subjectData\/meta\/insert_user\/login",
        "SRC": "0",
        "FIELD_ID": "INSERT_USER",
        "HEADER": "Creator",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Creator"
      },
      {
        "SUMMARY": "CASE xnat:demographicData\/gender WHEN 'male' THEN 'M' WHEN 'female' THEN 'F' ELSE 'U' END",
        "SRC": "0",
        "FIELD_ID": "GENDER_TEXT",
        "HEADER": "M\/F",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "M\/F"
      },
      {
        "SUMMARY": "CASE LOWER(xnat:demographicData\/handedness) WHEN 'left' THEN 'L' WHEN 'right' THEN 'R' WHEN 'ambidextrous' THEN 'A' WHEN 'r' THEN 'R' WHEN 'l' THEN 'L' WHEN 'a' THEN 'A' END",
        "SRC": "0",
        "FIELD_ID": "HANDEDNESS_TEXT",
        "HEADER": "Hand",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Hand"
      },
      {
        "SUMMARY": "CAST(FLOOR(COALESCE(xnat:demographicData\/yob,EXTRACT(YEAR FROM xnat:demographicData\/dob))) AS INTEGER)",
        "SRC": "0",
        "FIELD_ID": "DOB",
        "HEADER": "YOB",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "integer",
        "DESC": "YOB"
      },
      {
        "SUMMARY": "xnat:demographicData\/education",
        "SRC": "0",
        "FIELD_ID": "EDUC",
        "HEADER": "Education",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "integer",
        "DESC": "Education"
      },
      {
        "SUMMARY": "xnat:demographicData\/ses",
        "SRC": "0",
        "FIELD_ID": "SES",
        "HEADER": "Ses",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "integer",
        "DESC": "Ses"
      },
      {
        "SUMMARY": "xnat:subjectData\/investigator\/lastname",
        "SRC": "0",
        "FIELD_ID": "INVEST_CSV",
        "HEADER": "PI",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "PI"
      },
      {
        "SUMMARY": "SUB_PROJECTS.PROJECTS",
        "SRC": "0",
        "FIELD_ID": "PROJECTS",
        "HEADER": "Projects",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "All projects tied to a subject"
      },
      {
        "SUMMARY": "xnat:subjectData\/project",
        "SRC": "0",
        "FIELD_ID": "PROJECT",
        "HEADER": "Project",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Subject's primary project"
      },
      {
        "SUMMARY": "xnat:subjectData\/group",
        "SRC": "0",
        "FIELD_ID": "SUB_GROUP",
        "HEADER": "Group",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Group"
      },
      {
        "SUMMARY": "SUBJECT_IDS.ADDIDS",
        "SRC": "0",
        "FIELD_ID": "ADD_IDS",
        "HEADER": "Labels",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Labels"
      },
      {
        "SUMMARY": "xnat:demographicData\/race",
        "SRC": "0",
        "FIELD_ID": "RACE",
        "HEADER": "Race",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Race"
      },
      {
        "SUMMARY": "xnat:demographicData\/ethnicity",
        "SRC": "0",
        "FIELD_ID": "ETHNICITY",
        "HEADER": "Ethnicity",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Ethnicity"
      },
      {
        "SUMMARY": "xnat:mrSessionData\/LABEL",
        "SRC": "0",
        "FIELD_ID": "XNAT_COL_MRSESSIONDATALABEL",
        "HEADER": "LABEL",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "LABEL"
      },
      {
        "SUMMARY": "Label within the * project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=*",
        "HEADER": "*",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the * project."
      },
      {
        "SUMMARY": "Label within the BJC_Pat project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=BJC_Pat",
        "HEADER": "BJC_Pat",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the BJC_Pat project."
      },
      {
        "SUMMARY": "Label within the Behavior_DB project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=Behavior_DB",
        "HEADER": "Behavior_DB",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the Behavior_DB project."
      },
      {
        "SUMMARY": "Label within the Fruit_Struct project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=Fruit_Struct",
        "HEADER": "Fruit_Struct",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the Fruit_Struct project."
      },
      {
        "SUMMARY": "Label within the Nifti_Proc project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=Nifti_Proc",
        "HEADER": "Nifti_Proc",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the Nifti_Proc project."
      },
      {
        "SUMMARY": "Label within the QC_Review project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=QC_Review",
        "HEADER": "QC_Review",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the QC_Review project."
      },
      {
        "SUMMARY": "Label within the ResourceDemo project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=ResourceDemo",
        "HEADER": "ResourceDemo",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the ResourceDemo project."
      },
      {
        "SUMMARY": "Label within the UXE project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=UXE",
        "HEADER": "UXE",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the UXE project."
      },
      {
        "SUMMARY": "Label within the UXE_London project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=UXE_London",
        "HEADER": "UXE_London",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the UXE_London project."
      },
      {
        "SUMMARY": "Label within the UXE_NYC project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=UXE_NYC",
        "HEADER": "UXE_NYC",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the UXE_NYC project."
      },
      {
        "SUMMARY": "Label within the UXE_Seoul project.",
        "SRC": "2",
        "FIELD_ID": "SUB_PROJECT_IDENTIFIER=UXE_Seoul",
        "HEADER": "UXE_Seoul",
        "REQUIRES_VALUE": "false",
        "ELEMENT_NAME": "xnat:subjectData",
        "TYPE": "string",
        "DESC": "Label within the UXE_Seoul project."
      }
    ],
    "versions": {
      "DisplayVersions": {
        "element_name": "xnat:subjectData",
        "versions": [
          {
            "name": "brief",
            "orderBy": "SUBJECT_ID",
            "darkColor": "DEDEDE",
            "lightColor": "FFFFFF",
            "defaultSortOrder": "ASC",
            "fields": [
              {
                "id": "SUBJECT_LABEL",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "GENDER",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "HANDEDNESS",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "DOB",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "EDUC",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "SES",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              }
            ]
          },
          {
            "name": "project_bundle",
            "orderBy": "SUBJECTID",
            "darkColor": "DEDEDE",
            "lightColor": "FFFFFF",
            "defaultSortOrder": "ASC",
            "fields": [
              {
                "id": "SUB_PROJECT_IDENTIFIER",
                "element_name": "xnat:subjectData",
                "header": "Subject",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "GENDER_TEXT",
                "element_name": "xnat:subjectData",
                "header": "M\/F",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "HANDEDNESS_TEXT",
                "element_name": "xnat:subjectData",
                "header": "Hand",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "DOB",
                "element_name": "xnat:subjectData",
                "header": "YOB",
                "value": "null",
                "visible": "true"
              }
            ]
          },
          {
            "name": "listing",
            "orderBy": "SUBJECT_ID",
            "darkColor": "DEDEDE",
            "lightColor": "FFFFFF",
            "defaultSortOrder": "ASC",
            "fields": [
              {
                "id": "SUBJECT_LABEL",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "GENDER",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "HANDEDNESS",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "DOB",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "EDUC",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "SES",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              },
              {
                "id": "MR_COUNT",
                "element_name": "xnat:subjectData",
                "value": "null",
                "visible": "true"
              }
            ]
          },
          {
            "name": "all",
            "fields": [
              {
                "id": "SUBJECT_ID",
                "element_name": "xnat:subjectData",
                "header": "Subject",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "SUBJECTID",
                "element_name": "xnat:subjectData",
                "header": "Subject",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "INSERT_DATE",
                "element_name": "xnat:subjectData",
                "header": "Inserted",
                "type": "date",
                "visible": "true"
              },
              {
                "id": "INSERT_USER",
                "element_name": "xnat:subjectData",
                "header": "Creator",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "GENDER",
                "element_name": "xnat:subjectData",
                "header": "Gender",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "GENDER_TEXT",
                "element_name": "xnat:subjectData",
                "header": "M\/F",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "HANDEDNESS",
                "element_name": "xnat:subjectData",
                "header": "Hand",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "HANDEDNESS_TEXT",
                "element_name": "xnat:subjectData",
                "header": "Hand",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "DOB",
                "element_name": "xnat:subjectData",
                "header": "YOB",
                "type": "integer",
                "visible": "true"
              },
              {
                "id": "EDUC",
                "element_name": "xnat:subjectData",
                "header": "Education",
                "type": "integer",
                "visible": "true"
              },
              {
                "id": "SES",
                "element_name": "xnat:subjectData",
                "header": "Ses",
                "type": "integer",
                "visible": "true"
              },
              {
                "id": "MR_COUNT",
                "element_name": "xnat:subjectData",
                "header": "MR Count",
                "type": "integer",
                "visible": "true"
              },
              {
                "id": "INVEST_CSV",
                "element_name": "xnat:subjectData",
                "header": "PI",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "PROJECTS",
                "element_name": "xnat:subjectData",
                "header": "Projects",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "PROJECT",
                "element_name": "xnat:subjectData",
                "header": "Project",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "SUB_GROUP",
                "element_name": "xnat:subjectData",
                "header": "Group",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "SUBJECT_LABEL",
                "element_name": "xnat:subjectData",
                "header": "Subject",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "SHARED_LABEL",
                "element_name": "xnat:subjectData",
                "header": "Subject",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "ADD_IDS",
                "element_name": "xnat:subjectData",
                "header": "Labels",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "RACE",
                "element_name": "xnat:subjectData",
                "header": "Race",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "ETHNICITY",
                "element_name": "xnat:subjectData",
                "header": "Ethnicity",
                "type": "string",
                "visible": "true"
              },
              {
                "id": "XNAT_COL_MRSESSIONDATALABEL",
                "element_name": "xnat:subjectData",
                "header": "LABEL",
                "type": "string",
                "visible": "true"
              }
            ]
          }
        ]
      }
    },
    "element_name": "xnat:subjectData",
    "title": "Search Fields"
  }
}



Get A List Of Search Report Versions For A Data Type

In the Advanced Search UI, you will notice a set of options when joining two data types together, whether you want to join a "Brief" or "Detailed" view of the data. These are two defined search report versions for a given data type. There are also other defined versions that may be shown in various contexts. This REST endpoint returns a full list of those versions.

GET - /data/search/elements/{xsiType}/versions

Parameters

{xsiType}Required path parameter.
format

Optional querystring parameter. Specifies the format of the returned data

  • xml (default)
  • html
  • json
  • csv

Response:
Displays just the contents of the "versions" object in the xsiType search example listed above


  • No labels