Consumer Health

 

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

 

 

 

 

Searching Consumer Health Content

Basic Search

The Consumer Health API POST /content/search endpoint allows you to search Consumer Health content. 

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.

Request

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

Request Body

{
  "query": "chromosomal abnormalities",
  "fields": [
    "title"
  ]
}

The search above is for articles containing the words chromosomal and abnormalities.  The search will return only the title of the articles.  The pageSize query parameter used requested 10 items per page.

Note: The search engine removes punctuation from the search query term.  Therefore, a search for "chromosomal" and "abnormalities" is equivalent to a search for "chromosomal abnormalities" 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": "chromosomal abnormalities",
      "fields": [
        "title"
      ]
    },
    "links": [
      {
        "rel": "self",
        "href": "https://apis.ebsco.com/medsapi-consumer-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-consumer-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-consumer-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": "Chromosomal Abnormalities"
    }
  ]
}

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 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, only a list of article Ids and HATEOAS links are returned.

Request Body Parameters

All possible body request parameters are described below.

{
  "query": "chromosomal abnormalities",  
  "sort": "relevancy",
  "fields": [
    "title"
  ]
}
  • query - The term or terms to search for.  If query is not specified, all content will be searched.  To search for ICD-10 codes, just use the code in the query (e.g. "E11" - for Diabetes Melitus Type 2).
  • 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.
  • fields -  A list of one or more fields to be returned for each item.

Pay special attention to the spelling of fields.  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
  • type - Publication type of the articles to include
  • description- Description of the article
  • metadata - Additional information about the article

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

  • id of the article
  • link to the article

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-consumer-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-consumer-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-consumer-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-consumer-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-consumer-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-consumer-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-consumer-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-consumer-health/v1/content/articles/T913532"
        }
      ],
      "title": "Using a Bag-Mask in Adults"
    },
    {
      "id": "T915059",
      "links": [
        {
          "rel": "self",
          "href": "https://apis.ebsco.com/medsapi-consumer-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-consumer-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 Consumer Health search endpoint can return one of the error response codes.