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
  • Determine what fields are of interest

Request

POST 'https://ebscois-live.apigee.net/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, returning only the title of the articles.  The pageSize query parameter only 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"
      ]
    },
    "links": [
      {
        "rel": "self",
        "href": "https://ebscois-live.apigee.net/medsapi-dynamic-health/v1/content/search?page=1&pageSize=1&pageToken=id:rsid:43b68991-1656-4634-acb8-36bdea07f80a",
        "method": "post"
      },
      {
        "rel": "next",
        "href": "https://ebscois-live.apigee.net/medsapi-dynamic-health/v1/content/search?page=2&pageSize=1&pageToken=id:rsid:43b68991-1656-4634-acb8-36bdea07f80a",
        "method": "post"
      },
      {
        "rel": "last",
        "href": "https://ebscois-live.apigee.net/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 the original request. 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, then only a list of article Ids and HATEOAS links would be returned.  Note that the search DOES include custom articles for this location, but does NOT include articles which the administrator has chosen to hide.

List of all possible request body parameters

{
  "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 not specified, all content will be searched.
  • sort - May be one of: relevency, 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 criteia.  More below.
  • aggregations -  Fields or attributes by which to return aggregated item counts. More below. 
  • fields - this is a list of one or more fields to be returned for each item.

List of Fields that can be returned

These fields can be requested in the request body fields:

  • title - the title of the article matching the query term.
  • pubTypeId - publication type of the articles to include.
  • gender - the gender relevant to the article: All, Male, Female
  • population - the population relevant to the article: Adult, Pediatric
  • specialities - medical specialties relevant to the article.  Examples (not a complete list): General, Psychiatry, Obstetrics, Neurology & Neurosurgery, Infection Prevention, Surgery & Perioperative Care, Gastroenterology, 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.

These fields will always be returned when a query term matches:

  • id of the article
  • link to the article

List of Filters that can be requested

A list of filters can be applied to the search to narrow the search results.  These are set inside a filters object, and 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 at the https://ebscois-live.apigee.net/medsapi-dynamic-health/v1/content/categories endpoint. Alternatively, top-level categoryPaths can be obtained at this search endpoint by performing a search with the following request body: {"aggregations": ["categoryPath"]} .
  • populations - Possible values: Adult, Pediatric.
  • specialties - Medical specialities can be used to narrow down results.  Possible values can be derived by performing a search at this endpoint with the following request body: {"aggregations": ["specialties"]}.
  • genders - These are Male, Female and All
  • pubTypeIds - Publication type id 
  • 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 these fields you can use the following query:

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

Aggregations

List of Aggregations that can be requested

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. Note, 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, 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.

Requesting Aggregated Counts Example

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://ebscois-live.apigee.net/medsapi-dynamic-health/v1/content/search?pageSize=0'
{
  "query": "addiction",
  "aggregations": [
    "categoryPath"
  ]
}

Response Body

{
  "_metadata": {
    "pageToken": "id:rsid:198fbb22-aa8a-4cc6-a2c0-5642698f7e5e",
    "pageSize": 0,
    "page": 1,
    "totalPages": 1,
    "totalItems": 39,
    "request": {
      "query": "addiction",
      "aggregations": [
        "categoryPath"
      ]
    },
    "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://ebscois-live.apigee.net/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, next as appropriate.  In the initial response of paginated results, the page field in the _metadata.links.request section indicates the current page that was returned.  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://ebscois-live.apigee.net/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://ebscois-live.apigee.net/medsapi-dynamic-health/v1/content/search?page=3&pageSize=5&pageToken=id:rsid:74cf2886-b940-41db-a629-cf15ced4ae6e",
        "method": "post"
      },
      {
        "rel": "first",
        "href": "https://ebscois-live.apigee.net/medsapi-dynamic-health/v1/content/search?page=1&pageSize=5&pageToken=id:rsid:74cf2886-b940-41db-a629-cf15ced4ae6e",
        "method": "post"
      },
      {
        "rel": "prev",
        "href": "https://ebscois-live.apigee.net/medsapi-dynamic-health/v1/content/search?page=2&pageSize=5&pageToken=id:rsid:74cf2886-b940-41db-a629-cf15ced4ae6e",
        "method": "post"
      },
      {
        "rel": "next",
        "href": "https://ebscois-live.apigee.net/medsapi-dynamic-health/v1/content/search?page=4&pageSize=5&pageToken=id:rsid:74cf2886-b940-41db-a629-cf15ced4ae6e",
        "method": "post"
      },
      {
        "rel": "last",
        "href": "https://ebscois-live.apigee.net/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://ebscois-live.apigee.net/medsapi-dynamic-health/v1/content/articles/T913532"
        }
      ],
      "title": "Using a Bag-Mask in Adults"
    },
    {
      "id": "T915059",
      "links": [
        {
          "rel": "self",
          "href": "https://ebscois-live.apigee.net/medsapi-dynamic-health/v1/content/articles/T915059"
        }
      ],
      "title": "Resuscitation of the Newborn from Birth through Initial Hospitalization"
    },
    {
      "id": "T916640",
      "links": [
        {
          "rel": "self",
          "href": "https://ebscois-live.apigee.net/medsapi-dynamic-health/v1/content/articles/T916640"
        }
      ],
      "title": "Auscultating Heart Sounds in Children"
    }
  ]
}

 

Image and Video Responses

 Responses can include articles that have image and or videos associated with them. These include the title, copyright and an link to the actual image or video.  This link is valid for only 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://res.cloudinary.com/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://res.cloudinary.com/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.