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 to be returned for the request body.
  • The selected location for the current user.

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"
    ],
    "mediaTypes": [
      "videos"
    ]
  },
  "aggregations": [
    "categoryPath"
  ],
  "fields": [
    "title"
  ]
}
  • 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.

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.
  • 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.

{
  "filters":{
       "categoryPaths": [
         "Skills|Nursing Skills|Specialties|Emergency and Trauma"
       ],
       "populations": [
         "Adult"
       ],
       "specialties": [
         "Psychiatry"
       ],
       "genders": [
         "Female"
       ],
       "pubTypeIds": [
         "careintervention"
       ],
       "mediaTypes": [
         "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.
  • pubTypeIds - Publication type id to narrow the results. 
  • mediaTypes - Responses can be narrowed down to return articles with videos or images.

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

{​​​​​​​
    "aggregations": [
        "categoryPath",
        "mediaType",
        "specialties",
        "populations",
        "gender",
        "pubTypeId"
    ]
}​​​​​​​

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.
  • mediaType - The types of media in the article: video or images.
  • specialties - The medical specialties that an article aligns with.
  • populations - The populations that an article aligns with.
  • gender - The gender that an article aligns with.
  • pubTypeIds - 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 articles that have images and/or videos associated with them.  These include the title, copyright and a link to the actual image or video.  The link is valid for 24 hours and should not be cached.


"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"
       }
     ]
   }
 ]

 

Error Response Codes

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