MEDS API Documentation Title

 

 

Browse our guides and interact with our API reference for more information about MEDSAPI DynaMed. Try MEDSAPI DynaMed and learn about core concepts.

 

 

 

 

Searching DynaMed Content using POST

The DynaMed API POST /v2/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:

Request

POST 'https://apis.ebsco.com/medsapi-dynamed/v2/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,
        "searchTime": 10,
        "request": {
            "query": "heart attack",
            "fields": [
                "title"
            ]
        },
        "links": [
            {
                "rel": "self",
                "method": "post",
                "href": "https://apis.ebsco.com/medsapi-dynamed/v2/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/v2/content/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 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 Articlee Response Details and Image/Video Response Details sections below for more information.
 

Complete 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
mediaLinksFormat If set to server, will return a secure link in its original size.  "browser" (default), "server".
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.

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 publicatication 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 info is requested. 

Publication ID Publication Group Pretty Publication
image images  
ebmcalc calculators Calculator
video videos  
algorithm algorithms  
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 Use 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,
        "searchTime": 10,
        "request": {
            "query": "heart attack",
            "pageSize": 1,
            "filters": [
                {
                    "field": "pubTypeId",
                    "values": [
                        "drug",
                        "condition"
                    ]
                }
            ],
            "fields": [
                "title"
            ]
        },
        "links": {
            "rel": "self",
            "href": "https://apiss.ebsco.com/medsapi-dynamed/v2/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/v2/content/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 this:

{
  "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,
        "searchTime": 10,
        "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/v2/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 Use 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'.  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,
        "searchTime": 10,
        "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/v2/content/search"
            }
        ],
        "initiatedBy": "typed-in",
        "presentedAs": "result-list"
    },
    "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/v2/content/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 (example 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,
        "searchTime": 10,
        "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/v2/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,
        "searchTime": 10,
        "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/v2/content/search"
            }
        ],
        "initiatedBy": "paging",
        "presentedAs": "result-list",
    },
    "items": [
	.
	. item content omitted
	.
    ]
}

 

Article Response Details

Each item, with the exception of image, video, and algorithm 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/v2/articles/T193266"
        }
   ]
}

 

Requesting Media

Images and videos can be included in search responses.  To request images and videos, add filters that include the image or video id or group filters.  By default, the image and video response will return a https 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.

For some use cases, non-expiring media links are required. In this case, mediaLinksFormat can be set to "server", which will return a secure link to the image, video or algorithm in its original size. The link will include the file type. If a video is returned, it will return a poster of the video in the poster's original size. By default, mediLinksFormat is set to "browser", and does not need to be specified.

Example 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 (algorithm responses are similar):

{
    "_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/v2/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",
            "description": "Coronal illustrations of heart showing A) properly septated heart with complete atrial and ventricular septum; (B)....  ",
            "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, in addition to full (optimized for the browser making the request) 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/v2/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/v2/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.