Getting Started with the CEDAR API

The CEDAR API (the API for short) provides a standards-based unified search mechanism for the following repositories of patient centered outcomes research (PCOR) artifacts:

This page explains how to use CEDAR API to search for PCOR artifacts using a variety of criteria. It also provides links and information about the standards used by the CEDAR API and provides hints and tips for effective use of the API.

Intended Audience

This resource is aimed at software developers intending to write code that interacts with the API. Some familiarity with the Hypertext Transfer Protocol (HTTP), Uniform Resource Locators (URLs) and JavaScript Object Notation (JSON) is assumed.

Example Code

A simple demonstration C# console application that uses the CEDAR API is available as an example of API usage.

Open Source

The CEDAR software is available as open source on GitHub under the Apache 2.0 license. Source code is available for the three main CEDAR components:

CEDAR Admin - infrastructure that implements CEDAR's indexing capabilities and provides visibility into indexing status
CEDAR API - backend service that allows systems to access the data that CEDAR aggregates from source repositories
CEDAR UI - reference client application implementation that demonstrates the functionality offered by the CEDAR API

API Usage

The API is used via the simple HTTP request+response pattern. All API requests are read-only, use the HTTP GET method, and each request is standalone and idempotent.

Sample Request

For the first example we will search for PCOR artifacts related to hypertension. Copy the following URL into a browser or click this link.

https://cds.ahrq.gov/cedar/api/fhir/Citation?artifact-current-state=active&title:contains=hypertension&_count=10

Your browser will display several pages of JSON formatted data but, before we examine that, let's break down the URL into its component parts:

https://cds.ahrq.gov/cedar is the server address
/api is the root path of all API requests
/fhir is the sub path for all API requests that use the FHIR standard
/Citation identifies the type of FHIR resource being accessed, in this case Citation
Following these components are several URL query parameters that represent FHIR search parameters:
- artifact-current-state with a value of active ensures that only artifacts that are currently active (i.e. not archived or superseded) will be included in the returned results
- title:contains with a value of hypertension will search for artifacts whose title contains "hypertension" or a synonym of hypertension
- _count with a value of 10 limits the search to include only the first 10 matching results

Swagger / Open API

While learning the API, an alternative to manually creating the above URL (or writing code to do so) is to use the interactive CEDAR Swagger API description:

Visit the link above in a web browser
Locate the "Citation" section near the top of the page
Click the down arrow at the right of the "GET /Citation" line
Click the "Try it out" button at the top right of the box
Enter "hypertension" in the "title:contains" field
Enter "10" in the "_count" field
Click the "Execute" button

The result will show the API request URL that was created, an example of requesting that URL using the curl command line tool, and the actual data returned by the API as JSON.

The Swagger page provides a convenient interactive tool for exploring the API, creating requests, and viewing sample responses.

Sample Response

The API returns data in FHIR JSON format. Search results are returned as a FHIR Bundle of type searchset. Each entry in the search result bundle is a FHIR Citation resource that contains metadata about a PCOR artifact. The following fields of each Citation resource are typically populated:

id - a CEDAR-assigned unique identifier for the citation
url - the API URL that can be used to retrieve the citation individually rather than as part of a search result bundle
title - the title of the artifact
status - the status of the citation
date - the date the artifact was last updated in CEDAR
citedArtifact.identifier - a PCOR repository-assigned identifier for the artifact
citedArtifact.dateAccessed - the date the artifact was last updated in CEDAR
citedArtifact.currentState - the status of the cited artifact
citedArtifact.title - the title of the cited artifact
citedArtifact.abstract - the description of the cited artifact
citedArtifact.webLocation - the URL of the cited artifact in the source repository
citedArtifact.classification - the type of artifact, keywords and concepts that classify the cited artifact

Cited artifacts have separate keyword and concept classifiers. Note that keyword classifiers are assigned by the PCOR repository while concepts are assigned by CEDAR; see "Searching By Concept" below for further details.

The FHIR Citation definition documents the complete structure; that information is not repeated here for the sake of brevity.

Search Result Paging

As shown in the first example, the _count search parameter controls the number of results returned. Searches can return a large number of results so it is good practice to use this parameter to limit the size of the results. A companion search parameter, page, defines the starting point for the returned result. Together, these two parameters can be used to page through a large search result list (e.g., a combination of _count=10 and page=1 would return the first 10 results while _count=10 and page=2 would return results 11-20 inclusive).

Conveniently, the API also includes links in the returned Bundle.link element to make paging through a result list easy. Below is the set of paging links from the example above:

"total": 12,
"link": [
  {
    "relation": "self",
    "url": "https://cds.ahrq.gov/cedar/api/fhir/Citation?_count=10&artifact-current-state=active&page=1&title:contains=hypertension"
  },
  {
    "relation": "first",
    "url": "https://cds.ahrq.gov/cedar/api/fhir/Citation?_count=10&artifact-current-state=active&page=1&title:contains=hypertension"
  },
  {
    "relation": "last",
    "url": "https://cds.ahrq.gov/cedar/api/fhir/Citation?_count=10&artifact-current-state=active&page=2&title:contains=hypertension"
  },
  {
    "relation": "next",
    "url": "https://cds.ahrq.gov/cedar/api/fhir/Citation?_count=10&artifact-current-state=active&page=2&title:contains=hypertension"
  },
  ...
]

In the above, you can see that there are 12 matching results total, a link to the current page of results (self), a link to the first page of results (first), a link to the final page of results (last), and a link to the next page of results (next). These links can be used in applications to provide user-driven paging through large result sets.

Searching By Artifact Text

The API offers three text search parameters:

title - search for artifacts whose title starts with (one of) the supplied value(s). The search is case insensitive. Multiple values should be separated using commas (e.g., title=hypertension would search for artifacts whose title starts with "hypertension" while title=hypertension,hypotension would search for artifacts whose title starts with either "hypertension" or "hypotension").
title:contains - search for artifacts whose title includes (one of) the supplied value(s). Like title, the search is case insensitive and multiple values are separated by commas.
_content - free text search of artifact titles and descriptions with support for logical combinations of search terms and synonyms (e.g., _content=((hypertension OR hypotension) AND afib) would search the text of artifacts for those that include "hypertension" and "afib" or those that include "hypotension" and "afib"). The following logical operators are supported: AND, OR, and NOT. Search terms can be quoted and this will result in searches that looks for artifacts that contain the quoted words close together in their text (e.g., _content="atrial fibrillation" would search for artifacts where "atrial" and "fibrillation" appear close together in the text of the title or description).

Synonym Support

CEDAR uses the Unified Medical Language System (UMLS) to provide support for synonyms. Search terms sent in API requests are automatically expanded to a set of synonyms that are then used in queries (e.g., _content=afib would match artifacts that contain "afib", "af", "atrial fibrillation" or "auricular fibrillation" in their titles or descriptions).

The following search parameters support synonyms:

Free text search using the _content API parameter (see above)
Keyword search using the _classification:text API parameter (see below)

Searching By Keyword

Searching by artifact keyword uses the classification:text search paramater. Searching by artifact keyword is similar to the _content search described above. The same logical operators and synonyms are supported (e.g., classification:text=(afib OR "atrial flutter") would search for artifacts with any of the following keywords: "afib", "af", "atrial fibrillation", "auricular fibrillation", "atrial flutter").

Searching By Concept

CEDAR uses artifact keywords to identify related concepts via the UMLS (e.g., if an artifact has "hypertension" as a keyword, CEDAR would associate that artifact with MeSH D006973 (Blood Pressure, High) and SNOMED-CT 38341003 (Hypertensive disorder)). The API supports search by concept using the following code systems:

SNOMED-CT (http://snomed.info/sct)
MeSH (http://terminology.hl7.org/CodeSystem/MSH)
Medline Plus (http://www.nlm.nih.gov/research/umls/medlineplus)
SNOMED-CT (ESP) (http://snomed.info/sct/449081005)
MeSH (ESP) (http://www.nlm.nih.gov/research/umls/mshspa)
ICD-10-CM (http://hl7.org/fhir/sid/icd-10-cm)
RxNorm (http://www.nlm.nih.gov/research/umls/rxnorm)

Searching by artifact concept uses the classification search paramater (e.g., classification=http://terminology.hl7.org/CodeSystem/MSH|D006973 would search for artifacts associated with MeSH D006973 (Blood Pressure, High)). Note that the code system URI precedes the concept code separated by "|" as per the FHIR token search specification.

The code system URI prefix and "|" separator are optional. The earlier example could instead be written as classification=D006973. However, this would match the code D006973 in any of the above code systems and this could result in unexpected results when a given code is present in multiple code systems with different meanings. For this reason, it is recommended that the code system URI is always used in concept search requests.

MeSH Browser

The API also offers the ability to browse the MeSH concept hierarchy. This can be useful for constructing a user interface that provides direct search by MeSH concept.

Access to the MeSH concept hierarchy is via a custom FHIR operation get-mesh-children available at the following URL:

https://cds.ahrq.gov/cedar/api/fhir/CodeSystem/$get-mesh-children

An HTTP GET on the above URL will yield a FHIR Parameters resource that contains a list of the top level MeSH concepts, one of which is shown below:

{
  "name": "concept",
  "valueCoding": {
    "extension": [
      {
        "url": "https://cds.ahrq.gov/cedar/api/fhir/StructureDefinition/extension-mesh-tree-number",
        "valueCode": "E"
      },
      {
        "url": "https://cds.ahrq.gov/cedar/api/fhir/StructureDefinition/extension-mesh-has-children",
        "valueBoolean": true
      },
      {
        "url": "https://cds.ahrq.gov/cedar/api/fhir/StructureDefinition/extension-mesh-direct-artifact-count",
        "valueUnsignedInt": 0
      },
      {
        "url": "https://cds.ahrq.gov/cedar/api/fhir/StructureDefinition/extension-mesh-indirect-artifact-count",
        "valueUnsignedInt": 1340
      }
    ],
    "system": "http://terminology.hl7.org/CodeSystem/MSH",
    "display": "Analytical, Diagnostic and Therapeutic Techniques, and Equipment"
  }
}

In the above representation:

display provides the name of the concept ("Analytical, Diagnostic and Therapeutic Techniques, and Equipment")
The extension with url ending with extension-mesh-tree-number provides the MeSH tree number of the concept ("E")
The extension with url ending with extension-mesh-has-children indicates whether the concept has child concepts (true in this case)
The extension with url ending with extension-mesh-direct-artifact-count provides the number of artifacts in CEDAR that are associated with this concept (0 in this case)
The extension with url ending with extension-mesh-indirect-artifact-count provides the number of artifacts in CEDAR that are associated with descendents of this concept (1340 in this case)

To obtain the immediate children of a concept, issue a HTTP GET against the above URL and supply the tree number as the value of a code search parameter. For example, to obtain the children of the concept illustrated above with tree number "E", the URL would be:

https://cds.ahrq.gov/cedar/api/fhir/CodeSystem/$get-mesh-children?code=E

The resulting list is formatted the same as the top level concept list as shown above. For example:

{
  "name": "concept",
  "valueCoding": {
    "extension": [
      {
        "url": "https://cds.ahrq.gov/cedar/api/fhir/StructureDefinition/extension-mesh-tree-number",
        "valueCode": "E01"
      },
      {
        "url": "https://cds.ahrq.gov/cedar/api/fhir/StructureDefinition/extension-mesh-has-children",
        "valueBoolean": true
      },
      {
        "url": "https://cds.ahrq.gov/cedar/api/fhir/StructureDefinition/extension-mesh-direct-artifact-count",
        "valueUnsignedInt": 127
      },
      {
        "url": "https://cds.ahrq.gov/cedar/api/fhir/StructureDefinition/extension-mesh-indirect-artifact-count",
        "valueUnsignedInt": 273
      }
    ],
    "system": "http://terminology.hl7.org/CodeSystem/MSH",
    "code": "D003933",
    "display": "Diagnosis"
  }
}

The system and code values (note D003933 not the tree number E01) can be used in a concept search to retrieve a list of artifacts associated with that MeSH concept: classification=http://terminology.hl7.org/CodeSystem/MSH|D003933. See above for additional details on searching by concept.

Searching By Date

The API supports search by last modification date using the FHIR _lastUpdated search parameter (e.g., _lastUpdated=gt2021-10-26 would match any artifact updated after 10/26/2021). Note that the last modification date is the date that CEDAR last noted a change in an artifact (e.g., change in title text, description, keywords etc) - this may be different from the artifact publication date.

Dates can be specified with granularities of a day (formatted as YYYY-MM-DD), a month (formatted as YYYY-MM) or a year (formatted as YYYY). In all cases the date represents a range that encompasses the start of the specified period and the end of the specified period (e.g., "2021" represents any time that is both on or after midnight on 12/31/2020 and before midnight on 12/31/2021).

Dates can be compared using a variety of operators (e.g., gt in the above example); the full list is specified by the FHIR search specification. Also see how each operator works with dates.

Searching By Artifact Status

Each artifact in CEDAR has a status of:

draft: the artifact is a draft or other non-final form
active: the artifact is current
unknown: the artifact's status could not be determined
archived: the artifact is no longer current but is still available
retracted: the artfact's content has been removed from publication

The API supports searching by artifact status using the artifact-current-state search parameter (e.g., artifact-current-state=active selects artifacts known to be current). Multiple status values, separated by a comma, can be specified (e.g., artifact-current-state=active,unknown would select artifacts known to be current or whose status could not be determined).

Note that at least one artifact status is required for every search.

Searching By Artifact Publisher

As described earlier, CEDAR indexes external repositories of PCOR artifacts. Searches can be scoped to one or more repositories using the artifact-publisher search parameter (e.g., artifact-publisher=ehc,epc would select artifacts from the Effective Healthcare Program and Evidence-Based Practice Center repositories).

Repository List

The full list of repositories supported by CEDAR can be obtained from the following URL:

https://cds.ahrq.gov/cedar/api/fhir/Organization

Results are returned as a FHIR Bundle of type searchset. Each entry in the search result bundle is a FHIR Organization. The identifier used as the value of the artifact-publisher search parameter is the value of the Organization.id.

Supported repositories and their identifiers include:

ehc - Effective Healthcare Program
epc - Evidence-Based Practice Center
uspstf - United States Preventive Services Task Force
srdr - Systematic Review Data Repository
cds-connect - CDS Connect

Additional FHIR Resources

The API also makes available a number of FHIR resources that describe its capabilities:

metadata is the FHIR CapabilityStatement that includes links to custom FHIR SearchParameter and FHIR OperationDefinition resources:
- SearchParameter/cedar-citation-classification: search by concept
- SearchParameter/cedar-citation-artifact-current-state: search by artifact status
- SearchParameter/cedar-citation-artifact-publisher: search by artifact
- SearchParameter/cedar-citation-title: search by artifact title
- OperationDefinition/CodeSystem-get-mesh-children: for browsing the MeSH concept hierarchy

As illustrated earlier, the CodeSystem/$get-mesh-children operation utilizes four extensions to capture additional metadata about each MeSH concept. The formal definition of these extensions are as follows:

StructureDefinition/extension-mesh-direct-artifact-count: an extension to hold the count of artifact directly associated with a concept
StructureDefinition/extension-mesh-indirect-artifact-count: an extension to hold the count of artifact indirectly associated with a concept
StructureDefinition/extension-mesh-has-children: an extension to indicate whether a MeSH concept has child concepts
StructureDefinition/extension-mesh-tree-number: an extension to hold the MeSH tree number

Finally, related search links include an extension that provides the code, name and description of the associated MeSH concept. The formal definition of this extension is available at:

StructureDefinition/extension-mesh-concept: an extension to hold the MeSH concept that corresponds to a related search

Comma-Separated Values (CSV) Download

In addition to the FHIR API operation, the CEDAR API also offers the ability to download search results as a comma-separated values (CSV) file. The CSV download operation offers all of the same search parameters that are supported for the FHIR Citation search operation, only the URL path differs. Below is a sample request to the CSV endpoint:

https://cds.ahrq.gov/cedar/api/csv?artifact-current-state=active&title:contains=hypertension

Note that paging of results via the page and _count parameters is not supported for CSV.

Current CEDAR System Version Numbers:

Bitbucket Build
160

CEDAR Admin
37637d6 (v0.8.0)

CEDAR API
be38cb1 (v0.8.0)

CEDAR UI
5d7227b (v0.7.1)