The DynaMed API POST /content/search endpoint allows you to search DynaMed content, including images and videos. Search responses can be filtered to narrow responses.

Basic Search

To Perform a Basic Search (example):

Gather the following information for the request:

An access token. Please see Using the Client Credentials Grant for further information.
A word or phrase to search.

Request

POST 'https://apis.ebsco.com/medsapi-dynamed/v1/content/search'

Request Body

{
  "query": "heart attack",
  "fields": [
    "title"
  ]
}

The search above is for the URL encoded words 'heart' and 'attack', and requesting only the title of articles to be returned. This is a minimal request, and will return up to 30 items if possible.

Note: The search engine removes punctuation. Therefore, a search for heart attack is equivalent to a search for "heart attack" with no preference for the order of terms.

Response

Note: The response below is not a complete response. It has been truncated to highlight relevant fields.

{ 
   "_metadata": {
        "queryUsed": "heart attack",
        "pageToken": "id:rsid:936a2c18-177a-4a8a-86f1-4b6ab123456789",
        "page": 1,
        "pageSize": 30,
        "totalPages": 56,
        "totalItems": 1653,
        "request": {
            "query": "heart attack",
            "fields": [
                "title"
            ]
        },
        "links": [
            {
                "rel": "self",
                "method": "post",
                "href": "https://apis.ebsco.com/medsapi-dynamed/v1/content/search"
            }
        ],
        "initiatedBy": "typed-in",
        "presentedAs": "result-list",
        "searchTime": 411
    },
    "items": [
        {
            "id": "T916967",
            "title": "Complications of Myocardial Infarction",
            "links": [
                {
                    "rel": "self",
                    "href": "https://apis.ebsco.com/medsapi-dynamed/v1/articles/T916967"
                }
            ]
        }
.
. additional items omitted
.
    ]
}

The response is composed of two sections: _metadata and items. The _metadata section contains information about the results. The _metadata section has a searchTime. The searchTime is the number of milliseconds for the actual search. It does not reflect network latency. The _metadata section also contains a request section that identifies the original request body made by the caller. The items array will be formatted as either regular article or media (image/video) items (conditions, drugs etc). If the media items are mixed with article items, the items will still have the format appropriate for a media or an article. The items are sorted by best match order regardless of the order that publication type ids specified. See the Article Response Details and the Image/Video Response Details sections below for more information.

List of Request Body Attributes

Parameter Name	Description	Values
query	The word or words to search.	Any term in any language.
fields	Fields to return. This parameter is required	title, pubType, description, sections*, metadata, toc (table of contents)
filterType	The type of filter to apply. See next section for details.	pubTypeId, pubTypeGroup, pubTypePretty
filter	The filter to narrow results. See next section for details.	See next section.
aggregations	A list of publication types matching the request	pubTypeId, pubTypeGroup, pubTypePretty
page	The next page of results to retrieve.
pageToken	An identifier returned after the first call to be used in subsequent calls for the same request.
secure	Request media links to be returned as secure, https links.	true or false (if not specified, true)
queryLanguage	The language of the query term.	2 letter country codes from ISO 639-1
imageSize	The size(s) of the image returned in image links	small, medium, large, full
posterSize	The size(s) of poster returned when video links are returned	small, medium, large, full
initiatedBy	Adding the initiatedBy query parameter to the request will override the default value for both the response and the transaction logs.	"autocomplete", "autocorrect-override-link", "didyoumean-link", "typed-in", "voice-to-text".

Sections are only returned if they match in the section header. If metadata fields are requested, each item may include a slug. Also, in the links section of the item, it will contain an absolute URI to the item based on that slug.

Specifying Filters to Narrow Search Results

Filters can be used to narrow search results to one or more publication type or groups of publications. To use the filter attribute, you MUST specify the filterType, which can be either "pubTypeId", "pubTypeGroup" and/or "pubTtypePretty". The table below contains the current list of publication ids and publication groups that are available. The latest list of supported publication type ids can be retrieved using the medsapi-dynamed/v1/pubtypes endpoint. Pretty publication names, when available, return the same results as the publication id, but can be used to be clear about what type of information is requested.

Publication ID	Publication Group	Pretty Publication
image	images
ebmcalc	calculators	Calcluator
video	videos
algorithm	lgorithms
shared-decision-making	tools	SHARED DECISION-MAKING TOOL
drug	drugs	Drug Monograph
approachto	articles	Approach To Patient
condition	articles	Condition
device	articles	Device
drugreview	articles	Drug Review
evaluation	articles	Evaluation
lab	articles	Lab Monograph
management	articles	Management
prevention	articles	Prevention
procedure	articles	Procedure
quality	articles	Quality Improvement

To Retrieve DynaMed Content for Specific Publication Types (example):

Gather the information for the request:

An access token. Please see Using the Client Credentials Grant for further information.
A word or phrase to search.
The publication type ID(s) or publication groups desired.

Request Body

{
  "query": "heart attack",
  "pageSize": 1,
  "filters": [
    {
      "field": "pubTypeId",
      "values": [
        "drug",
        "condition"
      ]
    }
  ],
  "fields": [
    "title"
  ]
}

Response

{
    "_metadata": {
        "queryUsed": "heart attack",
        "pageToken": "id:rsid:11824a26-3f28-4f66-bafe-7d18a1eb5848",
        "page": 1,
        "pageSize": 1,
        "totalPages": 1156,
        "totalItems": 1156,
        "request": {
            "query": "heart attack",
            "pageSize": 1,
            "filters": [
                {
                    "field": "pubTypeId",
                    "values": [
                        "drug",
                        "condition"
                    ]
                }
            ],
            "fields": [
                "title"
            ]
        },
        "links": {
            "rel": "self",
            "href": "https://apiss.ebsco.com/medsapi-dynamed/v1/content/search"
        },
        "initiatedBy": "typed-in",
        "presentedAs": "result-list",
        "searchTime": 15
    },
    "items": [
        {
            "id": "T916967",
            "title": "Complications of Myocardial Infarction",
            "links": [
                {
                    "rel": "self",
                    "href": "https://apis.ebsco.com/medsapi-dynamed/v1/articles/T916967"
                }
            ]
        }
    ]
}

Getting Aggregated Counts

Aggregated counts for your filter term(s) can be returned in the response. For example, to return the number of pubTypeId, pubTypeGroup and pubTypePretty, the request body would look like the request body below.

{
  "query": "heart",
  "pageSize": 1,
  "filters": [
    {
      "field": "pubTypeId",
      "values": [
        "condition", "image"
      ]
    }
  ],
  "fields": [
    "title",
    "metadata"
  ],
  "aggregations": [
    "pubTypeId",
	"pubTypePretty",
	"pubTypeGroup"
  ],
  "initiatedBy": "typed-in"
}

Aggregated Response

{
    "_metadata": {
        "queryUsed": "heart",
        "pageToken": "id:rsid:aaabe2bf-b2ab-4519-8694-8310ad097056",
        "page": 1,
        "pageSize": 1,
        "totalPages": 1604,
        "totalItems": 1604,
        "request": {
            "query": "heart",
            "pageSize": 1,
            "filters": [
                {
                    "field": "pubTypeId",
                    "values": [
                        "condition",
                        "image"
                    ]
                }
            ],
            "fields": [
                "title",
                "metadata"
            ],
            "aggregations": [
                "pubTypeId",
                "pubTypePretty",
                "pubTypeGroup"
            ],
            "initiatedBy": "typed-in"
        },
        "links": [
            {
               "rel": "self",
               "method": "post",
               "href": "https://apis.ebsco.com/medsapi-dynamed/v1/content/search"
            }
        ],
        "initiatedBy": "typed-in",
        "presentedAs": "result-list",
        "searchTime": 18
    },
    "aggregations": [
        {
            "field": "pubTypeGroup",
            "counts": {
                "articles": 1550,
                "images": 54
            }
        },
        {
            "field": "pubTypeId",
            "counts": {
                "condition": 1550,
                "image": 54
            }
        },
        {
            "field": "pubTypePretty",
            "counts": {
                "Condition": 1550
            }
        }
    ],
    "items": [
        {
            "id": "I1604413732495",
            "contentLocations": {
                "parent": [
                    {
                        "title": "Atrioventricular (AV) Canal Defect",
                        "pubtype": "condition",
                        "slug": "/condition/atrioventricular-av-canal-defect"
                    }
                ],
                "anchor": "I1604413732495"
            },
            "title": "Anatomy of atrioventricular septation complex in human 4-chambered heart with normal anatomy and in hearts with AVSDs",
            "exactMatch": false,
            "mediaType": "image",
            "format": "png",
            "links": [
                {
                    "rel": "external",
                    "href": "https://res.cloudinary.com/eis-live/image/authenticated/f_auto/v1/EBSCOHealth/CCMS/Dynamed/images/I1604413732495?__cld_token__=exp=1688742373~hmac=521b6f4e4f3721c1200f78672d33d23f0f331b98d95655f09460102243b27c88"
                }
            ]
        }
    ]
}

Searching with a Non-English Query Term

Use the queryLanguage attribute to search for a query term from a non-english language. The queryLanguage parameter uses the 2 letter country codes from ISO 639-1 to specify the language. For example, the country code 'fr' specifies the language French.

To Perform a Non-English Query Term Search (example):

Gather the information for the request:

An access token. Please see Using the Client Credentials Grant for further information.
A non-english word or phrase to search. In the case below, the query is for coeur, the french word for heart.
The country code for the language that you are using to search. In the case below, 'fr' is used to specify French.

Note: The query word coeur is URL encoded.

Request Body

{
  "query": "cœur",
  "pageSize": 1,
  "filters": [
    {
      "field": "pubTypeGroup",
      "values": [
        "articles"
      ]
    }
  ],
  "queryLanguage": "fr",
  "page": 1,
  "fields": [
    "title",
    "description"
  ]
}

Response

The response will come back in English with the results that match the query term. The request section of the response will indicate the query specified by the request. In this example, the request section query will indicate cœur. In the _metadata section, queryUsed will indicate the English word that it actually searched for. In this example, the queryUsed is 'heart'. If no translation is needed, then both fields would be set to 'heart'.

If a valid language code was specified and no equivalent English term is found, the original term submitted will be used in the search.

{
    "_metadata": {
        "queryUsed": "heart",
        "pageToken": "id:rsid:65006ffb-20dc-4188-9384-6dd0a98f8676",
        "page": 1,
        "pageSize": 1,
        "totalPages": 2640,
        "totalItems": 2640,
        "request": {
            "query": "cœur",
            "pageSize": 1,
            "filters": [
                {
                    "field": "pubTypeGroup",
                    "values": [
                        "articles"
                    ]
                }
            ],
            "queryLanguage": "fr",
            "page": 1,
            "fields": [
                "title",
                "description"
            ]
        },
        "links": [
            {
                "rel": "self",
                "method": "post",
                "href": "https://apis.ebsco.com/medsapi-dynamed/v1/content/search"
            }
        ],
        "initiatedBy": "typed-in",
        "presentedAs": "result-list",
        "searchTime": 58
    },
    "items": [
        {
            "id": "T114099",
            "title": "Heart Failure With Reduced Ejection Fraction (HFrEF)",
            "description": "Heart failure with reduced ejection fraction (HFrEF) refers to heart failure with a left ventricular ejection fraction ≤ 40%.",
            "links": [
                {
                    "rel": "self",
                    "href": "https://apis.ebsco.com/medsapi-dynamed/v1/articles/T114099"
                }
            ]
        }
    ]
}

What to Expect When a Query Does Not Match

The search engine attempts to find the best possible matches for any query term or query phrase. If a word is misspelled in a phrase, the engine will use its medical knowledge base to find all permutations in order to determine the most likely intention of the search. The response will indicate in the _metadata section initiatedBy field that the response reflects a Did You Mean ("didyoumean-probe") query. If no matches can be found, an empty item list will be returned and the initiatedBy field will be "typed-in".

Request

{
  "query": "junqueterm",
  "pageSize": 1,
  "filters": [
    {
      "field": "pubTypeGroup",
      "values": [
        "articles"
      ]
    }
  ],
  "fields": [
    "title",
    "description"
  ]
}

Response

The example below is when the query term or phrase in the request does not match.

{
    "_metadata": {
        "queryUsed": "junqueterm",
        "pageToken": "id:rsid:93528d96-a85c-492f-8ff5-37c4a16d1453",
        "page": 1,
        "pageSize": 1,
        "totalPages": 0,
        "totalItems": 0,
        "request": {
            "query": "junqueterm",
            "pageSize": 1,
            "filters": [
                {
                    "field": "pubTypeGroup",
                    "values": [
                        "articles"
                    ]
                }
            ],
            "fields": [
                "title",
                "description"
            ]
        },
        "links": [
            {
                "rel": "self",
                "method": "post",
                "href": "https://apis.ebsco.com/medsapi-dynamed/v1/content/search"
            }
        ],
        "initiatedBy": "typed-in",
        "presentedAs": "result-list",
        "searchTime": 1
    },
    "items": []
}

Retrieving Paginated Results

Results that come back from the search engine are paginated. In the initial response of paginated results, the page field in the _metadata section indicates the current page returned. The total item count is the pageSize field in the _metadata section (or less if at the end of the results). A token, returned in the initial response, must be passed to the API to continue the search. The token is found in the pageToken field in the _metadata section. The value of the token has no particular meaning to the caller. The initiatedBy field found in the _metadata section of the response will be set to "paging" when paging information is included in the request parameters.

To Retrieve the Next Page After the Initial Search Request (example):

Request Body

{
  "query": "heart",
  "pageSize": 1,
  "pageToken": "id:rsid:d683e348-468e-4e2a-a1d9-1bae7be4333d",
  "page": 2,
  "filters": [
    {
      "field": "pubTypeGroup",
      "values": [
        "articles"
      ]
    }
  ],
  "fields": [
    "title"
  ]
}

Metadata Response

Note: The response below contains only the metadata.

{
    "_metadata": {
        "queryUsed": "heart",
        "pageToken": "id:rsid:d683e348-468e-4e2a-a1d9-1bae7be4333d",
        "page": 2,
        "pageSize": 1,
        "totalPages": 2640,
        "totalItems": 2640,
        "request": {
            "query": "heart",
            "pageSize": 1,
            "pageToken": "id:rsid:d683e348-468e-4e2a-a1d9-1bae7be4333d",
            "page": 2,
            "filters": [
                {
                    "field": "pubTypeGroup",
                    "values": [
                        "articles"
                    ]
                }
            ],
            "fields": [
                "title"
            ],
            "initiatedBy": "paging"
        },
        "links": [
            {
                "rel": "self",
                "method": "post",
                "href": "https://apis.ebsco.com/medsapi-dynamed/v1/content/search"
            }
        ],
        "initiatedBy": "paging",
        "presentedAs": "result-list",
        "searchTime": 42
    },
    "items": [
	.
	. item content omitted
	.
    ]
}

Article Response Details

Each item, with the exception of image and video results, will contain the following information:

{
   "id": "T193266", // ID of the resource
   "toc": [		// Table of Contents with an array of Titles for 
              // each section and anchor GUIDs to locate within the article [Only if requested in the fields attribute!]
      {
           "title": "Overview and Recommendations",
           "anchor": "GUID-5250DF0A-CBA8-416F-B438-11F7BBE324AF"
      },
   ],
   "title": "Heart Failure With Preserved Ejection Fraction",	// Title of the article
	 // The description shows a snippet of the text 
   // that matched
   "description": "Heart failure with preserved ejection fraction refers to clinical heart failure with a left ventricular ejection fraction ≥ 50%.", [Only if requested]
   "slug": "/condition/heart-failure-with-preserved-ejection-fraction",
   "exactMatch": true, // Indicates if the item was an exact match of the query term
   "sections": [ // Section(s) whose titles matched the query terms [Only if available and requested]
       {
           "anchor": "CARDIAC",
           "path": [
               "History and Physical ",
               " Physical ",
               "Cardiac"
           ],
           "title": "Cardiac"
       }
   ],
   "pubType": {
       "title": "Condition"	// publication type ID of this item
   },
   "links": [	// Link to the item that matched
       {
           "rel": "self",
           "href": "https://apis.ebsco.com/medsapi-dynamed/v1/articles/T193266"
        }
   ]
}

Requesting Media

Images and videos can be included in search responses. To request images and videos, add filters that include the image, video id or group filters. You MUST also request "metadata" in the fields so that a full link can be provided to the media. By default, the image and video response will return a http URl link that will expire in 24 hours. The secure image URL is a link to a full resolution image that is optimized for the browser making the request.

Image Request

{
  "query": "heart",
  "pageSize": 1,
  "filters": [
    {
      "field": "pubTypeId",
      "values": [
        "image"
      ]
    }
  ],
  "fields": [
    "title",
    "metadata"
  ]
}

Default Image Response Details

A default image response will contain the following information:

{
    "_metadata": {
        "queryUsed": "heart",
        "pageToken": "id:rsid:0b049856-8f7b-42e0-be5f-267b682f3962",
        "page": 1,
        "pageSize": 1,
        "totalPages": 54,
        "totalItems": 54,
        "request": {
            "query": "heart",
            "pageSize": 1,
            "filters": [
                {
                    "field": "pubTypeId",
                    "values": [
                        "image"
                    ]
                }
            ],
            "fields": [
                "title",
                "metadata"
            ]
        },
        "links": [
            {
                "rel": "self",
                "method": "post",
                "href": "https://apis.ebsco.com/medsapi-dynamed/v1/content/search"
            }
        ],
        "initiatedBy": "typed-in",
        "presentedAs": "result-list",
        "searchTime": 10
    },
    "items": [
        {
            "id": "I1604413732495",
            "contentLocations": {
                "parent": [
                    {
                        "title": "Atrioventricular (AV) Canal Defect",
                        "pubtype": "condition",
                        "slug": "/condition/atrioventricular-av-canal-defect"
                    }
                ],
                "anchor": "I1604413732495"
            },
            "title": "Anatomy of atrioventricular septation complex in human 4-chambered heart with normal anatomy and in hearts with AVSDs",
            "exactMatch": false,
            "mediaType": "image",
            "format": "png",
            "links": [
                {
                    "rel": "external",
                    "href": "https://res.cloudinary.com/eis-live/image/authenticated/f_auto/v1/EBSCOHealth/CCMS/Dynamed/images/I1604413732495?__cld_token__=exp=1688740727~hmac=025699d377d72ac66290c63089b6815ab86b8fe2ea794c5e6491959c26bed8c4"
                }
            ]
        }
    ]
}

Specifying Image and Video Image Sizes

Links to images of varying sizes can also be returned in the image response. To specify the image size, add one or more imageSize attributes to the body. small (200w), medium (500w) and large(1000w) are supported. Also, full (optimized for the browser making the request) is available and is the default if no image size was specified.

A still image of the video (aka thumbnail or poster) can also be returned with the video. To specify the size add one or more posterSize attributes to the body. Small, medium, large and full sized images of the video will be returned. To distinguish the video and video link in the response, a type parameter is added and is set to "poster".

Image Request with imageSize

{
  "query": "heart",
  "pageSize": 1,
  "filters": [
    {
      "field": "pubTypeId",
      "values": [
        "image"
      ]
    }
  ],
  "fields": [
    "title"
  ],
  "imageSize": ["small"]
}

Image Response when Specifying imageSize

{
    "_metadata": {
        "queryUsed": "heart",
        "pageToken": "id:rsid:a910eac9-10b3-40f7-bfb9-043ed24fd72c",
        "page": 1,
        "pageSize": 1,
        "totalPages": 54,
        "totalItems": 54,
        "request": {
            "query": "heart",
            "pageSize": 1,
            "filters": [
                {
                    "field": "pubTypeId",
                    "values": [
                        "image"
                    ]
                }
            ],
            "fields": [
                "title",
                "metadata"
            ],
            "imageSize": [
                "small"
            ]
        },
        "links": [
            {
                "rel": "self",
                "method": "post",
                "href": "https://apis.ebsco.com/medsapi-dynamed/v1/content/search"
            }
        ],
        "initiatedBy": "typed-in",
        "presentedAs": "result-list",
        "searchTime": 7
    },
    "items": [
        {
            "id": "I1604413732495",
            "contentLocations": {
                "parent": [
                    {
                        "title": "Atrioventricular (AV) Canal Defect",
                        "pubtype": "condition",
                        "slug": "/condition/atrioventricular-av-canal-defect"
                    }
                ],
                "anchor": "I1604413732495"
            },
            "title": "Anatomy of atrioventricular septation complex in human 4-chambered heart with normal anatomy and in hearts with AVSDs",
            "exactMatch": false,
            "mediaType": "image",
            "format": "png",
            "links": [
                {
                    "rel": "external",
                    "imageSize": "small",
                    "href": "https://res.cloudinary.com/eis-live/image/authenticated/t_s200/f_auto/v1/EBSCOHealth/CCMS/Dynamed/images/I1604413732495?__cld_token__=exp=1688741579~hmac=44a99de5d486cf1adf52479cb89bfb462dfdb45ee7b047571da46975583efe1d"
                }
            ]
        }
    ]
}

Video Response when Specifying Small and Large Poster Sizes

{
    "_metadata": {
        "queryUsed": "heart",
        "pageToken": "id:rsid:98d8f67d-f8e7-4b1e-a751-7634702d6841",
        "page": 1,
        "pageSize": 1,
        "totalPages": 33,
        "totalItems": 33,
        "request": {
            "query": "heart",
            "pageSize": 1,
            "filters": [
                {
                    "field": "pubTypeId",
                    "values": [
                        "video"
                    ]
                }
            ],
            "fields": [
                "title",
                "metadata"
            ],
            "posterSize": [
                "small",
                "large"
            ]
        },
        "links": [
            {
                "rel": "self",
                "method": "post",
                "href": "https://apis.ebsco.com/medsapi-dynamed/v1/content/search"
            }
        ],
        "initiatedBy": "typed-in",
        "presentedAs": "result-list",
        "searchTime": 7
    },
    "items": [
        {
            "id": "V1620308757808",
            "contentLocations": {
                "parent": [
                    {
                        "title": "Cardiovascular Physical Exam in Adults",
                        "pubtype": "evaluation",
                        "slug": "/evaluation/cardiovascular-physical-exam-in-adults"
                    }
                ],
                "anchor": "V1620308757808"
            },
            "title": "Auscultating S1 and S2 heart sounds",
            "exactMatch": false,
            "mediaType": "video",
            "format": "mp4",
            "links": [                    // This is the link to the video
                {
                    "rel": "external",
                    "href": "http://media.ebsco.healthcare/eis-live/video/authenticated/f_mp4/v1/EBSCOHealth/CCMS/Dynamed/videos/V1620308757808.mp4?__cld_token__=exp=1688739530~hmac=dcf35a69d07769e5c1ff51499a8835515f9d535c4f08ee4af48d7d25d23a5a02"
                },
                {
                    "rel": "external",    // Small and large poster sizes
                    "posterSize": "small",
                    "type": "poster",
                    "href": "http://media.ebsco.healthcare/eis-live/video/authenticated/t_s200/f_jpg/v1/EBSCOHealth/CCMS/Dynamed/videos/V1620308757808.mp4?__cld_token__=exp=1688739530~hmac=5f758b9fde164bb8f47fb10395add7c32c4a6e8ff7868ed8dc85b99a3817b194"
                },
                {
                    "rel": "external",
                    "posterSize": "large",
                    "type": "poster",
                    "href": "http://media.ebsco.healthcare/eis-live/video/authenticated/t_s1000/f_jpg/v1/EBSCOHealth/CCMS/Dynamed/videos/V1620308757808.mp4?__cld_token__=exp=1688739530~hmac=414e40eb371cbac3336b7e2a8dbc4b442195636b171e3a60fe28d7a8e5f827db"
                }
            ]
        }
    ]
}

Error Response Codes

The DynaMed search endpoint can return one of the error response codes.