Searching DynaMed Content using GET (Deprecated)
The DynaMed API GET /search endpoint allows you to search DynaMed content, including images and videos. The GET endpoint is deprecated in favor of the POST. Search responses can be filtered to narrow responses.
- Basic Search
- List of Parameters
- Specifying Filters to Use in Queries
- Searching with Non-English Query Term
- What to Expect When a Query Does Not Match
- Retrieving Paginated Results
- Article Response Details
- Requesting Media
- Error Response Codes
To Perform a Basic Search (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.
Request
GET 'https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart%20attack'
The search above is for the URL encoded words 'heart' and 'attack'.
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": { "initiatedBy": "typed-in", "presentedAs": "result-list", "pageToken": "id:rsid:22a054fe-f2e3-4caf-88ee-2a3d2b651679", "searchTime": 205, "totalItems": 942, "queryUsed": "heart attack", "pageSize": 10, "totalPages": 95, "page": 1, "aggregations": [], "request": { "query": "heart attack" }, "links": [ { "rel": "self", "href": "https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart%20attack" }, { "rel": "first", "href": "https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart%20attack&pageToken=id:rsid:22a054fe-f2e3-4caf-88ee-2a3d2b651679&page=1" }, { "rel": "last", "href": "https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart%20attack&pageToken=id:rsid:22a054fe-f2e3-4caf-88ee-2a3d2b651679&page=95" }, { "rel": "next", "href": "https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart%20attack&pageToken=id:rsid:22a054fe-f2e3-4caf-88ee-2a3d2b651679&page=2" }, { "rel": "pubTypes", "href": "https://apis.ebsco.com/medsapi-dynamed/v1/pubTypes" } ] }, "items": [ { "id": "T916967", "toc": [ { "title": "Overview and Recommendations", "anchor": "GUID-1717F8A2-2C34-4B48-9402-23886B9187DE" }, { "title": "Etiology and Pathogenesis", "anchor": "GUID-F5F98554-4292-4C25-BDA1-E6C0270593E1" }, - - - { "title": "References", "anchor": "GUID-BD7F9F70-F6D2-4ED4-A0A5-DEF6057FAC35" } ], "exactMatch": false, "title": "Complications of Myocardial Infarction", "description": "The majority of complications present within 24 hours after acute myocardial infarction, with most others occurring within 7 days.", "slug": "/condition/complications-of-myocardial-infarction", "sections": [ { "anchor": "EMBOLIC_AND_BLEEDING_COMPLICATIONS_AFTER_MYOCARDIAL_INFARCTION", "path": [ "Prognosis ", "Embolic and bleeding complications after myocardial infarction" ], "title": "Embolic and bleeding complications after myocardial infarction" }, { "anchor": "INFLAMMATORY_COMPLICATIONS_AFTER_MYOCARDIAL_INFARCTION", "path": [ "Prognosis " ], "title": "Inflammatory complications after myocardial infarction" }, { "anchor": "ELECTRICAL_COMPLICATIONS_AFTER_MYOCARDIAL_INFARCTION", "path": [ "Prognosis ", "Electrical complications after myocardial infarction" ], "title": "Electrical complications after myocardial infarction" } ], "pubType": { "title": "Condition" }, "links": [ { "rel": "self", "href": "https://apis.ebsco.com/medsapi-dynamed/v1/articles/T916967" } ] }, . . . { "id": "T114250", "toc": [ { "title": "Overview and Recommendations", "anchor": "GUID-3F4AC031-291E-48FC-B1F2-BF34E2F4314D" }, - - - { "title": "References", "anchor": "GUID-E33F5BF6-7FD6-4E1D-A98F-CB76D9CFECB5" } ], "title": "Hypercholesterolemia", "description": "Hypercholesterolemia is a condition characterized by elevated serum levels of total and low-density lipoprotein (LDL) cholesterol.", "slug": "/condition/hypercholesterolemia", "sections": [], "pubType": { "title": "Condition" }, "links": [ { "rel": "self", "href": "https://apis.ebsco.com/medsapi-dynamed/v1/articles/T114250" } ] } ] }
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 section also contains a request section that identifies the original request 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 Article Response Details and Image/Video Response Details sections below for more information.
Complete List of Request Parameters
| Parameter Name | Description | Values |
|---|---|---|
| query | The word or words to search | Any term in any language |
| filterType | The type of filter to apply. See next section for details | id, group |
| filter | The filter to narrow results. See next section for details | See next section |
| 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 query value | |
| secure | Request media links to be returned as secure, https links. | true or false (default is false) |
| 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 |
| 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". |
| includeToC | Indicates whether the Table of Contents will be returned for each article. | true or flse (default is true) |
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 parameter, you MUST specify the filterType, which can be either "id" OR "group". The table below contains the current list of publication Ids and groups that are available. The latest list of supported publication type IDs can be retrieved using the medsapi-dynamed/v1/pubtypes endpoint.. Alternate 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 | Group | Alternate Publication ID |
|---|---|---|
| image | images | |
| ebmcalc | Calculator | calculators |
| video | videos | |
| 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 groups desired. When specifying the path, the filter can be specified as a comma separated list: &filter=drug,condition.
Request
GET 'https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart%20attack&filterType=id&filter=drug&filter=condition'
Response
Note: The response below is not a complete response. It has been truncated to highlight the relevant fields when filtering by a publication Id. When a filter is requested, aggregations will also be returned.
{
"_metadata": {
"page": 1,
"pageSize": 10,
"totalPages": 18,
"totalItems": 179,
"links": [
{
"rel": "self",
"href": "https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart%20attack&filterType=id&filter=condition&filter=drug&pageToken=id:rsid:fcc1f541-139f-43bd-823b-26db0b4e3568&page=1"
},
{
"rel": "first",
"href": "https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart%20attack&filterType=id&filter=condition&filter=drug&pageToken=id:rsid:fcc1f541-139f-43bd-823b-26db0b4e3568&page=1"
},
{
"rel": "last",
"href": "https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart%20attack&filterType=id&filter=condition&filter=drug&pageToken=id:rsid:fcc1f541-139f-43bd-823b-26db0b4e3568&page=18"
},
{
"rel": "next",
"href": "https://apis.ebsco.comt/medsapi-dynamed/v1/search?query=heart%20attack&filterType=id&filter=condition&filter=drug&pageToken=id:rsid:fcc1f541-139f-43bd-823b-26db0b4e3568&page=2"
},
{
"rel": "pubTypes",
"href": "https://apis.ebsco.com/medsapi-dynamed/v1/pubTypes"
}
],
"request": {
"query": "heart attack",
"filterType": "id",
"filters": [
"condition",
"drug"
]
},
"initiatedBy": "typed-in",
"presentedAs": "result-list",
"pageToken": "id:rsid:fcc1f541-139f-43bd-823b-26db0b4e3568",
"searchTime": 571,
"queryUsed": "heart attack",
"aggregations": [
{
"field": "pubTypeId",
"counts": {
"condition": 114,
"drug": 65
}
}
]
},
"items": [
{
"id": "T916967",
"title": "Complications of Myocardial Infarction",
"description": "The majority of complications present within 24 hours after acute myocardial infarction, with most others occurring within 7 days.",
"slug": "/condition/complications-of-myocardial-infarction",
"sections": [],
"exactMatch": false,
"pubType": {
"title": "Condition"
},
"links": [
{
"rel": "self",
"href": "https://apis.ebsco.com/medsapi-dynamed/v1/articles/T916967"
}
],
"toc": [
{
"anchor": "GUID-1717F8A2-2C34-4B48-9402-23886B9187DE",
"title": "Overview and Recommendations"
},
...
{
"anchor": "GUID-BD7F9F70-F6D2-4ED4-A0A5-DEF6057FAC35",
"title": "References"
}
]
},
...
]
}
The response will include an aggregation count for each pubTypeId that was specified. Each item will indicate the type of publication type that it was found in. If no matches were found, the count will be 0 for the pubTypeId.
Searching with a Non-English Query Term
Use the queryLanguage parameter 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
GET 'https://apis.ebsco.com/medsapi-dynamed/v1/search?query=%0Ac%C5%93ur&queryLanguage=fr&filterType=id&filter=condition&filter=drug'
Response
The response will come back in English with the results that match the criteria. The request section of the response will indicate the query specified by the request. In this example, the request section 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.
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
GET 'https://apis.ebsco.com/medsapi-dynamed/v1/search?query=kwsdewasfwer&filterType=id&filter=condition&filter=drug
Response (example when the query term or phrase in the Request does not match)
{
"_metadata": {
"initiatedBy": "typed-in",
"totalItems": 0,
"queryUsed": "kwsdewasfwer",
"page": 1,
"pageSize": 0,
"request": {
"query": "kwsdewasfwer",
"filterType": "id",
"filter": [
"condition",
"drug"
]
}
},
"items": []
}
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, so the next page will be one more. 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. As a convenience, the results also include the HATEAOS links for retrieving the first, last, previous, next and the pubTypeIds.
To Retrieve the Next Page After the Initial Search Request (example):
Request
GET 'https://apis.ebsco.com/medsapi-dynamed/v1/search?query=%0Ac%C5%93ur&queryLanguage=fr&filterType=id&filter=condition&filter=drug&pageToken=id:rsid:7b111036-5e79-4d9d-bfb1-5a416c31e781&page=11'
Metadata Response
Note: The response below contains only the metadata.
"_metadata": { "pageToken": "id:rsid:eea02f73-9596-4861-9ea7-beb8e5f390e6", "totalItems": 2289, "queryUsed": "heart", "page": 21, // The next page to GET would be page 21 "pageSize": 10, // Each page will contain 10 items (or less if no more results are // found on the last page) "totalPages": 229, // You would need to make 229 search calls to see all the results. // Each subsequent page would contain less relevant content. "links": [ { "rel": "self", "href": "https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart&filterType=id&filter=condition&filter=drug&pageToken=id%3Arsid%3Aeea02f73-9596-4861-9ea7-beb8e5f390e6&page=11" }, { "rel": "first", "href": "https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart&filterType=id&filter=condition&filter=drug&pageToken=id:rsid:eea02f73-9596-4861-9ea7-beb8e5f390e6&page=1&pageSize=10" }, { "rel": "last", "href": "https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart&filterType=id&filter=condition&filter=drug&pageToken=id:rsid:eea02f73-9596-4861-9ea7-beb8e5f390e6&page=229&pageSize=10" }, { "rel": "next", "href": "https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart&filterType=id&l;filter=condition&filter=drug&pageToken=id:rsid:eea02f73-9596-4861-9ea7-beb8e5f390e6&page=21&pageSize=10" }, { "rel": "prev", "href": "https://apis.ebsco.com/medsapi-dynamed/v1/search?query=heart&filterType=id&filter=condition&filter=drug&pageToken=id:rsid:eea02f73-9596-4861-9ea7-beb8e5f390e6&page=11&pageSize=10" }, { "rel": "pubTypes", "href": "https://apis.ebsco.com/medsapi-dynamed/v1/pubTypes" } ] }, "request": { "query": "heart", "filterType": "id", "filters": [ "condition", "drug" ], "pageToken": "id%3Arsid%3Aeea02f73-9596-4861-9ea7-beb8e5f390e6", "page": "20" // The page that is requested }
Each item, with the exception of image and video 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 { "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%.", "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 { "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/v1/articles/T193266" } ] }
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 http URl link that will expire in 24 hours. The image URL is a link to a full resolution image that is optimized for the browser making the request. The caller can alternately request that secure URLs (https) be returned by specify the secure=true parameter.
Default Image Response Details
A default image response will contain the following information:
{ "id": "I509101", // ID of the image "title": "Left parasternal long axis view of heart.", // Title of the image "format": "jpg", // Type of image "exactMatch": false, // Indicates if the title is an exact match of the query term "mediaType": "image" // Type of media "links": [ // Link to get the image { "rel": "external", "href": "http://media.ebsco.healthcare/eis-live/image/authenticated/f_auto/v1/EBSCOHealth/CCMS/I509101?__cld_token__=exp=1590236397~hmac=cb9faf1f9188138b0d1c73944bc70c2d75c605a84e599a5af07139d35db8375f" } ], "contentLocations": { // An array of article locations where the image is used "parent": { [ "title": "Ultrasound in the Intensive Care Unit (ICU)", "slug": "/evaluation/ultrasound-in-the-intensive-care-unit-icu", "pubtype": "approachto" ] }, "anchor": "I509101" } }
Default Video Response Details
A video response contains a link to a video. The video link is only valid for 24 hours. A video response will contain the following information:
{ "id": "V1622166482467", "title": "Recognizing Transfusion-Related Acute Lung Injury (TRALI).", "format": "mp4", "mediaType": "video", "exactMatch": false, "description": "This video shows...", "links": [ { "rel": "external", "href": "http://media.ebsco.healthcare/eis-live/video/authenticated/v1/EBSCOHealth/videos/V1622166482467?__cld_token__=exp=1589920019~hmac=318fc29d454df2a4f122307ee5" } ], "contentLocations": { "parent": { [ "title": "Asthma in Adults and Adolescents", "slug": "/condition/asthma-in-adults-and-adolescents" ] }, "anchor": "V1622166355451" } }
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 query parameters to the call, small (200w), medium (500w) and large(1000w) are supported, in addition to full which was described above 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 parameters to the call. Small, medium large and full sized images of the video will be returned. To distinguish the vdeo and video link in the response, a type parameter is added and is set to "poster".
Image response when specifying size
{
"id": "I509101", // ID of the image
"title": "Left parasternal long axis view of heart.", // Title of the image
"links": [ // Link to get the image
{
"rel": "external",
"imageSize": "small",
"href": "https://media.ebsco.healthcare/eis-live/image/authenticated/t_s200/f_auto/v1/EBSCOHealth/CCMS/Dynamed/images/I504630?__cld_token__=exp=1659810699~hmac=cbb101584fd25ed877ebe6ac6d35063253deabfbed9c53b7a40b8313b7689044"
}
],
"contentLocations": { // An object containing an array of article locations where the image is used
"parent": {
[
"title": "Ultrasound in the Intensive Care Unit (ICU)",
"slug": "/evaluation/ultrasound-in-the-intensive-care-unit-icu"
]
},
"anchor": "I509101"
}
}Video response contains when specifying size
{
"id": "V1622166482467",
"title": "Recognizing Transfusion-Related Acute Lung Injury (TRALI).",
"format": "mp4",
"description": "This video shows...",
"links": [
{
"rel": "external",
"href": "https://media.ebsco.healthcare/eis-live/video/authenticated/f_mp4/v1/EBSCOHealth/CCMS/Dynamed/videos/V1626216419424.mp4?__cld_token__=exp=1659810699~hmac=bcb9a5de9c17c1b640ee0855fbf0c6b5508ec8239868e3640804456ec9f48077"
},
{
"rel": "external",
"posterSize": "large",
"type": "poster",
"href": "https://media.ebsco.healthcare/eis-live/video/authenticated/t_s1000/f_jpg/v1/EBSCOHealth/CCMS/Dynamed/videos/V1626216419424.mp4?__cld_token__=exp=1659810699~hmac=5000ac1908b199459216948f66fa58dd7490fba10016350b3526cb195636f2c2""
}
],
"contentLocations": {
"parent": [
{
"title": "Asthma in Adults and Adolescents",
"slug": "/condition/asthma-in-adults-and-adolescents"
}
],
"anchor": "V1622166355451"
}
}
The DynaMed search endpoint can return one of the error response codes.