MEDSAPI Dynamic Health Documentation Title

 

 

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

 

 

 

 

Searching Dynamic Health Content

Basic Search

The Dynamic Health API POST /content/search endpoint allows you to search Dynamic Health content.  The search endpoint provides numerous ways to filter on the articles of interest and allows for limiting the responses to the fields and information of interest.

To Perform a Basic Search for Article Titles matching a Term (example):

Gather the following information for the request:

  • An access token. Please see Use the Client Credentials Grant for further information.
  • A word or phrase to search and the desired fields and filters to be returned for the request body.

Request

POST 'https://apis.ebsco.com/medsapi-dynamic-health/v1/content/search?pageSize=1'

Request Body

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

The search above is for articles containing the words heart and attack.  The search will return only the title of the articles.  The pageSize query parameter used requested one item per page.

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

Response Body

{
  "_metadata": {
    "pageToken": "id:rsid:43b68991-1656-4634-acb8-36bdea07f80a",
    "pageSize": 1,
    "page": 1,
    "totalPages": 167,
    "totalItems": 167,
    "request": {
      "query": "heart attack",
      "fields": [
        "title"
      ]
    },
    "searchSegments": [
       "token": "tylenol",
       "synonyms": [
          "acetaminophen"
       ]
    ],
    "links": [
      {
        "rel": "self",
        "href": "https://apis.ebsco.com/medsapi-dynamic-health/v1/content/search?page=1&pageSize=1&pageToken=id:rsid:43b68991-1656-4634-acb8-36bdea07f80a",
        "method": "post"
      },
      {
        "rel": "next",
        "href": "https://apis.ebsco.com/medsapi-dynamic-health/v1/content/search?page=2&pageSize=1&pageToken=id:rsid:43b68991-1656-4634-acb8-36bdea07f80a",
        "method": "post"
      },
      {
        "rel": "last",
        "href": "https://apis.ebsco.com/medsapi-dynamic-health/v1/content/search?page=167&pageSize=1&pageToken=id:rsid:43b68991-1656-4634-acb8-36bdea07f80a",
        "method": "post"
      }
    ]
  },
  "items": [
    {
      "id": "T1601009663264",
      "links": [
        {
          "rel": "self",
          "href": "/content/articles/T1601009663264"
        }
      ],
      "title": "Panic Disorder"
    }
  ]
}

The response is composed of two sections: _metadata and items. The _metadata section contains information about the results.  The _metadata.totalItems indicates that there are 167 articles that match this request.  The _metadata section also contains a links section that identifies the self link and paging links, searchSegments and the original request.  searchSegments indicates the term or terms that were used in the search.  In some cases, a synonym for a search term will also be returned. The items are sorted by best match unless otherwise specified.  A default pageSize is set to 30 if it is not specified.  If no fields are specified, only a list of article Ids and HATEOAS links are returned.  The search DOES include custom articles for this location, but does NOT include articles that the administrator has chosen to hide.

Request Body Parameters

All possible body request parameters are described below.

{ 
 "query": "addiction",  
  "sort": "relevancy",
  "filters": {
    "categoryPaths": [
      "Skills|Nursing Skills|Specialties|Emergency and Trauma"
    ],
    "populations": [
      "Adult"
    ],
    "specialties": [
      "Psychiatry"
    ],
    "genders": [
      "Female"
    ],
    "pubTypeIds": [
      "careintervention"
    ],
    "pubTypeGroup": [
      "videos"
    ]
  },
  "aggregations": [
    "categoryPath"
  ],
  "fields": [
    "title"
  ],
  "secure": "true",
  "imageSizes": [
    "medium",
    "full"
  ],
  "posterSizes": [
    "small"
  ]
}
  • query - The term or terms to search for.  If query is not specified, all content will be searched.
  • sort - May be one of: relevancy, title or categoryPath.  By default, the results are returned in the best match (relevancy) order.  However, alphabetic ordering of the title or by the order of the categoryPath are also possible.
  • filters - These allow results to be filtered on specific criteria.  Please see the Filters Body Request Parameter section below. 
  • aggregations -  Fields or attributes by which to return aggregated item counts.  Please see the Aggregations Body Request Parameter section below. 
  • fields -  A list of one or more fields to be returned for each item.
  • secure - If true, return media URLs as secure (https) links.
  • imageSizes - One or more image sizes to return in image links.
  • posterSizes - One or more poster (thumbnail) sizes to return in video links.

Pay special attention to the spelling of fields, aggregations etc. Specifying a singular when a plural is expected could result in a 400 unknown request response.

Fields Body Request Parameter

The fields below can be requested in the request body fields parameter:

  • title - The title of the article matching the query term.
  • pubType - Publication type of the articles to include.
  • description - Some response may include a description of the article or media.
  • gender - The gender relevant to the article: All, Male or Female.
  • populations - The population relevant to the article: Adult or Pediatric.
  • specialties - Medical specialties relevant to the article.  Examples (not a complete list): General, Psychiatry, Obstetrics, Neurology & Neurosurgery, Infection Prevention, Surgery & Perioperative Care, Gastroenterology and Endocrinology.
  • images - Images relevant to the article including copyright, title of the image and link to the image.
  • videos - Videos relevant to the article including the copyright, video title and link to the video.
  • toc - Table of contents.
  • hitSummary - A field containing boolean value used to indicate if this item matches the title exactly.
  • slug - The part of the article URL that comes after the domain.

The fields below will always be returned when a query term matches:

  • id of the article
  • link to the article

Filters Body Request Parameter

A list of filters can be applied to the search to narrow the search results.  The filters are set inside a filters object.  Each filter type can have an array of string values. Note that filters are cumulative - so all filters must match in a given article or meida in order to be returned.

{
  "filters":{
       "categoryPaths": [
         "Skills|Nursing Skills|Specialties|Emergency and Trauma"
       ],
       "populations": [
         "Adult"
       ],
       "specialties": [
         "Psychiatry"
       ],
       "genders": [
         "Female"
       ],
       "contentSets": [
         "Skills|Transcultural Care Skills|African-American"
       ],
       "pubTypeIds": [
         "careintervention"
       ],
       "pubTypeGroup": [
         "videos"
       ]
     }
}
  • categoryPaths - These can be obtained using the https://apis.ebsco.com/medsapi-dynamic-health/v1/content/categories endpoint.  Alternatively, top-level categoryPaths can be obtained using the search endpoint by performing a search with the following request body: {"aggregations": ["categoryPath"]}.
  • populations - Populations used to narrow the results: Adult or Pediatric.
  • specialties - Medical specialities used to narrow the results.  Possible values can be derived by using the search endpoint with the following request body: {"aggregations": ["specialties"]}.
  • genders - Genders used to narrow the results: Male, Female or All.
  • contentSets - Content to include
  • pubTypeIds - Publication type id to narrow the results. 
  • pubTypeGroup - Responses can be narrowed down to return articles with videos or images.
  • mediaType - [Deprecated] - use pubTypeGroup

Note: To get a list of all possible values for any of the fields, you can use the following query:

{​​​​​​​
    "aggregations": [
        "categoryPath",
        "pubTypeGroup",
        "specialties",
        "populations",
        "contentSets",
        "gender",
        "pubTypeId"
    ],
    "fields": [
       "pubType"
    ]
}​​​​​​​

Aggregations Body Request Parameter

Aggregations are used to return a list of counts of how many articles match a particular aggregation type.  When a query term is found to be relevant in an article in one of these aggregation types, the count will be incremented.  If you ONLY want agregation counts but do NOT want a list of items matching the query, set pageSize to 0.

  • categoryPath - The category that an article aligns with.
  • pubTypeGroup - The types of media in the article: video or images.
  • mediaType - [Deprecated] use pubTypeGroup
  • specialties - The medical specialities that an article aligns with.
  • populations - The populations that an article aligns with.
  • contentSets - Content to include.
  • gender - The gender that an article aligns with.
  • pubTypeId - The publication type of an article.

Example Request - Requesting Aggregated Counts 

In this example, the caller is requesting counts of articles containing the term addiction.  Because a pageSize of zero was requested in the query parameters, no items and no paging HATEAOS links will be returned.

Request

POST 'https://apis.ebsco.com/medsapi-dynamic-health/v1/content/search?pageSize=0'

{
  "query": "tylenol",
  "aggregations": [
    "categoryPath"
  ]
}

Response Body

{
  "_metadata": {
    "pageToken": "id:rsid:198fbb22-aa8a-4cc6-a2c0-5642698f7e5e",
    "pageSize": 0,
    "page": 1,
    "totalPages": 1,
    "totalItems": 39,
    "request": {
      "query": "tylenol",
      "aggregations": [
        "categoryPath"
      ]
    },
    "searchSegments": [
      {
        "token": "tylenol",
        "synonyms": [
          "acetaminophen"
        ]
      }
    ],
    "links": [
      {
        "rel": "self",
        "href": "/content/search?page=0&pageSize=0&pageToken=id:rsid:198fbb22-aa8a-4cc6-a2c0-5642698f7e5e",
        "method": "post"
      }
    ],
    "aggregations": [
      {
        "field": "categoryPath",
        "counts": {
          "Diseases & Conditions": 6,
          "Drug Monographs": 1,
          "Signs & Symptoms": 1,
          "Skills": 28
        }
      }
    ]
  }
}

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 no matches can be found, an empty item list will be returned.

Request Body

{
  "query": "bedd"
}

Response (example when the query term or phrase in the request does not match)

{
  "_metadata": {
    "pageToken": "id:rsid:396f6413-d5dd-486e-94cc-22c96d0ee14d",
    "pageSize": 1,
    "page": 1,
    "totalPages": 0,
    "totalItems": 0,
    "request": {
      "query": "bedd"
    },
    "links": [
      {
        "rel": "self",
        "href": "https://apis.ebsco.com/medsapi-dynamic-health/v1/content/search?page=1&pageSize=1&pageToken=id:rsid:396f6413-d5dd-486e-94cc-22c96d0ee14d",
        "method": "post"
      }
    ]
  },
  "items": []
}

 

Retrieving Paginated Results

Results that come back from the search engine are paginated.   As a convenience, the results also include the HATEAOS links for retrieving the first, last, previous and next as appropriate.  In the initial response of paginated results, the page field in the _metadata.links.request section indicates the current page.  A page token, returned in the  _metadata.pageToken, must be passed to the API to continue the search.  The value of the token has no particular meaning to the caller.  Since the _metadata.request contains the original request, using the next href  from the HATEOAS link will get the next page of items.  If there is no next, then the last page of results have already been retrieved.   The maximum number of items that can be returned on a page is 30.  If a pageSize is not specified, 30 will be used as the pageSize.

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

POST 'https://apis.ebsco.com/medsapi-dynamic-health/v1/content/search?pageSize=2&page=3&pageToken=id%3Arsid%3A74cf2886-b940-41db-a629-cf15ced4ae6e'

Request Body

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

Response

{
  "_metadata": {
    "pageToken": "id:rsid:74cf2886-b940-41db-a629-cf15ced4ae6e",
    "pageSize": 2,
    "page": 3,
    "totalPages": 554,
    "totalItems": 1107,
    "request": {
      "query": "heart",
      "fields": [
        "title"
      ]
    },
    "links": [
      {
        "rel": "self",
        "href": "https://apis.ebsco.com/medsapi-dynamic-health/v1/content/search?page=3&pageSize=5&pageToken=id:rsid:74cf2886-b940-41db-a629-cf15ced4ae6e",
        "method": "post"
      },
      {
        "rel": "first",
        "href": "https://apis.ebsco.com/medsapi-dynamic-health/v1/content/search?page=1&pageSize=5&pageToken=id:rsid:74cf2886-b940-41db-a629-cf15ced4ae6e",
        "method": "post"
      },
      {
        "rel": "prev",
        "href": "https://apis.ebsco.com/medsapi-dynamic-health/v1/content/search?page=2&pageSize=5&pageToken=id:rsid:74cf2886-b940-41db-a629-cf15ced4ae6e",
        "method": "post"
      },
      {
        "rel": "next",
        "href": "https://apis.ebsco.com/medsapi-dynamic-health/v1/content/search?page=4&pageSize=5&pageToken=id:rsid:74cf2886-b940-41db-a629-cf15ced4ae6e",
        "method": "post"
      },
      {
        "rel": "last",
        "href": "https://apis.ebsco.com/medsapi-dynamic-health/v1/content/search?page=222&pageSize=5&pageToken=id:rsid:74cf2886-b940-41db-a629-cf15ced4ae6e",
        "method": "post"
      }
    ]
  },
  "items": [
    {
      "id": "T913532",
      "links": [
        {
          "rel": "self",
          "href": "https://apis.ebsco.com/medsapi-dynamic-health/v1/content/articles/T913532"
        }
      ],
      "title": "Using a Bag-Mask in Adults"
    },
    {
      "id": "T915059",
      "links": [
        {
          "rel": "self",
          "href": "https://apis.ebsco.com/medsapi-dynamic-health/v1/content/articles/T915059"
        }
      ],
      "title": "Resuscitation of the Newborn from Birth through Initial Hospitalization"
    },
    {
      "id": "T916640",
      "links": [
        {
          "rel": "self",
          "href": "https://apis.ebsco.com/medsapi-dynamic-health/v1/content/articles/T916640"
        }
      ],
      "title": "Auscultating Heart Sounds in Children"
    }
  ]
}

 

Image and Video Responses

Responses can include items that have images and/or videos.  These include the title, copyright and a link to the actual image or video.  The image URL is a link to a full resolution image that is optimized for the browser making the request. The link is valid for 24 hours and should not be cached. The caller can alternately request that secure URLs (https) be returned by specifying that secure=true in the request body. 


"images": [
   {
     "copyright": "Copyright© Madhero88, 2011. Licensed under Creative Commons Attribution-Share Alike 3.0 Unported License",
     "title": "Heel Sticks On a Newborn Or Infant.",
     "links": [
        {
             "rel": "external",
             "href": "http://media.ebsco.healthcare/eis-live/image/authenticated/f_auto/v1/EBSCOHealth/CCMS/I509101?__cld_token__=exp=1590236397~hmac=cb9fa19867467"
        }
     ]
   }
 ],
 "videos": [
   {
     "copyright": "Copyright© Madhero88, 2011. Licensed under Creative Commons Attribution-Share Alike 3.0 Unported License",
     "title": "Performing a Heelstick in an Infant.",
     "links": [
       {
            "rel": "external",
            "href": "http://media.ebsco.healthcare/eis-live/image/authenticated/f_auto/v1/EBSCOHealth/CCMSVI589121?__cld_token__=exp=1590236397~hmac=cb9faf1f91881"
       }
     ]
   }
 ]

Requesting Media Sizes

The search API may return images and videos when requested in the filter parameters. The default image of full size may not always be desired.  The caller can request one or more image sizes through the imageSizes parameter in the request body.  Additionally, a caller can request a still image (poster or thumbnail) of a video through the posterSizes paremeter.  When the posterSizes parameter is specified, the video will be returned and also one or more posters of the video in the size(s) requested.

Request Body


{
  "query": "heart",
  "sort": "relevancy",
  "secure": "true",
  "imageSizes": ["medium", "full"],
  "posterSizes":["small"],
  "filters": {
    "mediaTypes": [
      "videos", "images"
    ]
  },
  "aggregations": [
    "categoryPath"
  ],
  "fields": [
    "title",
    "images",
    "videos"
  ]
}

 

Response Body 

Note that secure URLs were requested and image and poster sizes were added to the response below.

{
    "_metadata": {...},
    "items": [
        {
            "id": "T914631",
            "links": [
                {
                    "rel": "self",
                    "href": "https://ebscois-development-devqa.apigee.net/medsapi-dynamic-health/v1/content/articles/T914631"
                }
            ],
            "title": "Performing Cardiac Fetal Monitoring Using Doppler Or Fetoscope",
            "images": [
                {
                    "copyright": "Copyright ©2018, EBSCO Information Services",
                    "title": "Fetoscope and Doppler Ultrasound Device. ",
                    "anchor": "NURSING_CONSIDERATIONS__FIG_X1F_FWD_VFB",
                    "links": [
                        {
                            "rel": "external",
                            "imageSize": "medium",
                            "href": "https://res.cloudinary.com/eis-live/image/authenticated/t_s500/f_auto/v1/EBSCOHealth/CCMS/NAH/images/123626752?__cld_token__=exp=1660158057~hmac=158ffe5f167350b953fadf6ee71fdfda4e38bf1885acfa50121cb2998d746d9d"
                        },
                        {
                            "rel": "external",
                            "imageSize": "full",
                            "href": "https://res.cloudinary.com/eis-live/image/authenticated/f_auto/v1/EBSCOHealth/CCMS/NAH/images/123626752?__cld_token__=exp=1660158057~hmac=65962bc45f9b54a21674dad3e636b2cf1ac89a6b15326ba0002f8f6e43d1f520"
                        }
                    ]
                }
            ],
            "videos": [
                {
                    "copyright": "Copyright ©2018, EBSCO Information Services",
                    "title": "Cardiac Fetal Monitoring. ",
                    "anchor": "PROCEDURE_STEPS__FIG_SP3_PWD_VFB",
                    "links": [
                        {
                            "rel": "external",
                            "href": "https://res.cloudinary.com/eis-live/video/authenticated/f_mp4/v1/EBSCOHealth/CCMS/NAH/videos/9f08dbac6011e1a10c3c04a478015e34.mp4?__cld_token__=exp=1660158057~hmac=ad387a0c8f3637689059a8893cd5d6e9c5672ea3142a6fd77de55f5cf649e86e"
                        },
                        {
                            "rel": "external",
                            "posterSize": "small",
                            "type": "poster",
                            "href": "https://res.cloudinary.com/eis-live/video/authenticated/t_s200/f_jpg/v1/EBSCOHealth/CCMS/NAH/videos/9f08dbac6011e1a10c3c04a478015e34.mp4?__cld_token__=exp=1660158057~hmac=6b46b0d1ec63fb825bbb1f93186bfba778af1b2024a3d3a9c5e8dfaf25370cfe"
                        }
                    ]
                }
            ]
        }
    ]
}

 

Error Response Codes

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