Searching DynaMed/DynaMedex Content using POST
The DynaMed API POST /v2/content/search endpoint allows you to search DynaMed content, including images and videos. Search responses can be filtered to narrow responses.
- Basic Search
- List of Request Body Attributes
- Specifying Filters to Use in Queries
- Getting Aggregated Counts
- 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
POST 'https://
apis.ebsco.com/medsapi-dynamed/v2/content/search'
Request Body
{ "query": "heart attack", "fields": [ "title" ] }
The search above is for the URL encoded words 'heart' and 'attack', and requesting only the title of articles to be returned. This is a minimal request, and will return up to 30 items if possible.
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": {
"queryUsed": "heart attack",
"pageToken": "id:rsid:936a2c18-177a-4a8a-86f1-4b6ab123456789",
"page": 1,
"pageSize": 30,
"totalPages": 56,
"totalItems": 1653,
"searchTime": 10,
"request": {
"query": "heart attack",
"fields": [
"title"
]
},
"links": [
{
"rel": "self",
"method": "post",
"href": "https://apis.ebsco.com/medsapi-dynamed/v2/content/search"
}
],
"initiatedBy": "typed-in",
"presentedAs": "result-list",
"searchTime": 411
},
"items": [
{
"id": "T916967",
"title": "Complications of Myocardial Infarction",
"links": [
{
"rel": "self",
"href": "https://apis.ebsco.com/medsapi-dynamed/v2/content/articles/T916967"
}
]
}
.
. additional items omitted
.
]
}
Complete List of Request Body Attributes
Parameter Name | Description | Values |
---|---|---|
query | The word or words to search | Any term in any language |
fields | Fields to return. This parameter is required. | title, pubType, description, sections*, metadata, toc (table of contents) |
filterType | The type of filter to apply. See next section for details | pubTypeId, pubTypeGroup, pubTypePretty |
filter | The filter to narrow results. See next section for details | See next section |
aggregations | A list of publication types matching the request | pubTypeId, pubTypeGroup, pubTypePretty |
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 request | |
secure | Request media links to be returned as secure, https links. | true or false (if not specified, true) |
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 |
mediaLinksFormat | If set to server, will return a secure link in its original size. | "browser" (default), "server". |
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". |
*Sections are only returned if they match in the section header. If metadata fields are requested each item may include a slug. Then in the links section of the item, it will contain an absolute URI to the item based on that slug.
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 attribute, you MUST specify the filterType, which can be either "pubTypeId", "pubTypeGroup" and/or "pubTtypePretty". The table below contains the current list of publication Ids and publicatication groups that are available. The latest list of supported publication type IDs can be retrieved using the medsapi-dynamed/v1/pubtypes endpoint.. Pretty 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 | Publication Group | Pretty Publication |
---|---|---|
image | images | |
ebmcalc | calculators | Calculator |
video | videos | |
algorithm | algorithms | |
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 publication groups desired.
Request Body
{
"query": "heart attack",
"pageSize": 1,
"filters": [
{
"field": "pubTypeId",
"values": [
"drug",
"condition"
]
}
],
"fields": [
"title"
]
}
Response
{
"_metadata": {
"queryUsed": "heart attack",
"pageToken": "id:rsid:11824a26-3f28-4f66-bafe-7d18a1eb5848",
"page": 1,
"pageSize": 1,
"totalPages": 1156,
"totalItems": 1156,
"searchTime": 10,
"request": {
"query": "heart attack",
"pageSize": 1,
"filters": [
{
"field": "pubTypeId",
"values": [
"drug",
"condition"
]
}
],
"fields": [
"title"
]
},
"links": {
"rel": "self",
"href": "https://apiss.ebsco.com/medsapi-dynamed/v2/content/search"
},
"initiatedBy": "typed-in",
"presentedAs": "result-list",
"searchTime": 15
},
"items": [
{
"id": "T916967",
"title": "Complications of Myocardial Infarction",
"links": [
{
"rel": "self",
"href": "https://apis.ebsco.com/medsapi-dynamed/v2/content/articles/T916967"
}
]
}
]
}
Aggregated counts for your filter term(s) can be returned in the response. For example, to return the number of pubTypeId, pubTypeGroup and pubTypePretty, the request body would look like this:
{
"query": "heart",
"pageSize": 1,
"filters": [
{
"field": "pubTypeId",
"values": [
"condition", "image"
]
}
],
"fields": [
"title",
"metadata"
],
"aggregations": [
"pubTypeId",
"pubTypePretty",
"pubTypeGroup"
],
"initiatedBy": "typed-in"
}
Aggregated response
{ "_metadata": { "queryUsed": "heart", "pageToken": "id:rsid:aaabe2bf-b2ab-4519-8694-8310ad097056", "page": 1, "pageSize": 1, "totalPages": 1604, "totalItems": 1604, "searchTime": 10, "request": { "query": "heart", "pageSize": 1, "filters": [ { "field": "pubTypeId", "values": [ "condition", "image" ] } ], "fields": [ "title", "metadata" ], "aggregations": [ "pubTypeId", "pubTypePretty", "pubTypeGroup" ], "initiatedBy": "typed-in" }, "links": [ { "rel": "self", "method": "post", "href": "https://apis.ebsco.com/medsapi-dynamed/v2/content/search" } ], "initiatedBy": "typed-in", "presentedAs": "result-list", "searchTime": 18 }, "aggregations": [ { "field": "pubTypeGroup", "counts": { "articles": 1550, "images": 54 } }, { "field": "pubTypeId", "counts": { "condition": 1550, "image": 54 } }, { "field": "pubTypePretty", "counts": { "Condition": 1550 } } ], "items": [ { "id": "I1604413732495", "contentLocations": { "parent": [ { "title": "Atrioventricular (AV) Canal Defect", "pubtype": "condition", "slug": "/condition/atrioventricular-av-canal-defect" } ], "anchor": "I1604413732495" }, "title": "Anatomy of atrioventricular septation complex in human 4-chambered heart with normal anatomy and in hearts with AVSDs", "exactMatch": false, "mediaType": "image", "format": "png", "links": [ { "rel": "external", "href": "https://res.cloudinary.com/eis-live/image/authenticated/f_auto/v1/EBSCOHealth/CCMS/Dynamed/images/I1604413732495?__cld_token__=exp=1688742373~hmac=521b6f4e4f3721c1200f78672d33d23f0f331b98d95655f09460102243b27c88" } ] } ] }
Searching with a Non-English Query Term
Use the queryLanguage attribute 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 Body
{
"query": "cœur",
"pageSize": 1,
"filters": [
{
"field": "pubTypeGroup",
"values": [
"articles"
]
}
],
"queryLanguage": "fr",
"page": 1,
"fields": [
"title",
"description"
]
}
Response
The response will come back in English with the results that match the query term. The request section of the response will indicate the query specified by the request. In this example, the request section query 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.
{
"_metadata": {
"queryUsed": "heart",
"pageToken": "id:rsid:65006ffb-20dc-4188-9384-6dd0a98f8676",
"page": 1,
"pageSize": 1,
"totalPages": 2640,
"totalItems": 2640,
"searchTime": 10,
"request": {
"query": "cœur",
"pageSize": 1,
"filters": [
{
"field": "pubTypeGroup",
"values": [
"articles"
]
}
],
"queryLanguage": "fr",
"page": 1,
"fields": [
"title",
"description"
]
},
"links": [
{
"rel": "self",
"method": "post",
"href": "https://apis.ebsco.com/medsapi-dynamed/v2/content/search"
}
],
"initiatedBy": "typed-in",
"presentedAs": "result-list"
},
"items": [
{
"id": "T114099",
"title": "Heart Failure With Reduced Ejection Fraction (HFrEF)",
"description": "Heart failure with reduced ejection fraction (HFrEF) refers to heart failure with a left ventricular ejection fraction ≤ 40%.",
"links": [
{
"rel": "self",
"href": "https://apis.ebsco.com/medsapi-dynamed/v2/content/articles/T114099"
}
]
}
]
}
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
{ "query": "junqueterm", "pageSize": 1, "filters": [ { "field": "pubTypeGroup", "values": [ "articles" ] } ], "fields": [ "title", "description" ] }
Response (example when the query term or phrase in the Request does not match)
{ "_metadata": { "queryUsed": "junqueterm", "pageToken": "id:rsid:93528d96-a85c-492f-8ff5-37c4a16d1453", "page": 1, "pageSize": 1, "totalPages": 0, "totalItems": 0, "searchTime": 10, "request": { "query": "junqueterm", "pageSize": 1, "filters": [ { "field": "pubTypeGroup", "values": [ "articles" ] } ], "fields": [ "title", "description" ] }, "links": [ { "rel": "self", "method": "post", "href": "https://apis.ebsco.com/medsapi-dynamed/v2/content/search" } ], "initiatedBy": "typed-in", "presentedAs": "result-list", "searchTime": 1 }, "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 returned. 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.
To Retrieve the Next Page After the Initial Search Request (example):
Request Body
{
"query": "heart",
"pageSize": 1,
"pageToken": "id:rsid:d683e348-468e-4e2a-a1d9-1bae7be4333d",
"page": 2,
"filters": [
{
"field": "pubTypeGroup",
"values": [
"articles"
]
}
],
"fields": [
"title"
]
}
Metadata Response
Note: The response below contains only the metadata.
{
"_metadata": {
"queryUsed": "heart",
"pageToken": "id:rsid:d683e348-468e-4e2a-a1d9-1bae7be4333d",
"page": 2,
"pageSize": 1,
"totalPages": 2640,
"totalItems": 2640,
"searchTime": 10,
"request": {
"query": "heart",
"pageSize": 1,
"pageToken": "id:rsid:d683e348-468e-4e2a-a1d9-1bae7be4333d",
"page": 2,
"filters": [
{
"field": "pubTypeGroup",
"values": [
"articles"
]
}
],
"fields": [
"title"
],
"initiatedBy": "paging"
},
"links": [
{
"rel": "self",
"method": "post",
"href": "https://apis.ebsco.com/medsapi-dynamed/v2/content/search"
}
],
"initiatedBy": "paging",
"presentedAs": "result-list",
},
"items": [
.
. item content omitted
.
]
}
Each item, with the exception of image, video, and algorithm 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 [Only if requested in the fields attribute!] { "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%.", [Only if requested] "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 [Only if available and requested] { "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/v2/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 https URl link that will expire in 24 hours. The secure image URL is a link to a full resolution image that is optimized for the browser making the request.
For some use cases, non-expiring media links are required. In this case, mediaLinksFormat can be set to "server", which will return a secure link to the image, video or algorithm in its original size. The link will include the file type. If a video is returned, it will return a poster of the video in the poster's original size. By default, mediLinksFormat is set to "browser", and does not need to be specified.
Example Image Request
{ "query": "heart", "pageSize": 1, "filters": [ { "field": "pubTypeId", "values": [ "image" ] } ], "fields": [ "title", "metadata" ] }
Default Image Response Details
A default image response will contain the following information (algorithm responses are similar):
{ "_metadata": { "queryUsed": "heart", "pageToken": "id:rsid:0b049856-8f7b-42e0-be5f-267b682f3962", "page": 1, "pageSize": 1, "totalPages": 54, "totalItems": 54, "request": { "query": "heart", "pageSize": 1, "filters": [ { "field": "pubTypeId", "values": [ "image" ] } ], "fields": [ "title", "metadata" ] }, "links": [ { "rel": "self", "method": "post", "href": "https://apis.ebsco.com/medsapi-dynamed/v2/content/search" } ], "initiatedBy": "typed-in", "presentedAs": "result-list", "searchTime": 10 }, "items": [ { "id": "I1604413732495", "contentLocations": { "parent": [ { "title": "Atrioventricular (AV) Canal Defect", "pubtype": "condition", "slug": "/condition/atrioventricular-av-canal-defect" } ], "anchor": "I1604413732495" }, "title": "Anatomy of atrioventricular septation complex in human 4-chambered heart with normal anatomy and in hearts with AVSDs", "description": "Coronal illustrations of heart showing A) properly septated heart with complete atrial and ventricular septum; (B).... ", "exactMatch": false, "mediaType": "image", "format": "png", "links": [ { "rel": "external", "href": "https://res.cloudinary.com/eis-live/image/authenticated/f_auto/v1/EBSCOHealth/CCMS/Dynamed/images/I1604413732495?__cld_token__=exp=1688740727~hmac=025699d377d72ac66290c63089b6815ab86b8fe2ea794c5e6491959c26bed8c4" } ] } ] }
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 attributes to the body, small (200w), medium (500w) and large(1000w) are supported, in addition to full (optimized for the browser making the request) 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 attributes to the body. Small, medium large and full sized images of the video will be returned. To distinguish the video and video link in the response, a type parameter is added and is set to "poster".
Image Request with imageSize
{ "query": "heart", "pageSize": 1, "filters": [ { "field": "pubTypeId", "values": [ "image" ] } ], "fields": [ "title" ], "imageSize": ["small"] }
Image response when specifying imageSize
{
"_metadata": {
"queryUsed": "heart",
"pageToken": "id:rsid:a910eac9-10b3-40f7-bfb9-043ed24fd72c",
"page": 1,
"pageSize": 1,
"totalPages": 54,
"totalItems": 54,
"request": {
"query": "heart",
"pageSize": 1,
"filters": [
{
"field": "pubTypeId",
"values": [
"image"
]
}
],
"fields": [
"title",
"metadata"
],
"imageSize": [
"small"
]
},
"links": [
{
"rel": "self",
"method": "post",
"href": "https://apis.ebsco.com/medsapi-dynamed/v2/content/search"
}
],
"initiatedBy": "typed-in",
"presentedAs": "result-list",
"searchTime": 7
},
"items": [
{
"id": "I1604413732495",
"contentLocations": {
"parent": [
{
"title": "Atrioventricular (AV) Canal Defect",
"pubtype": "condition",
"slug": "/condition/atrioventricular-av-canal-defect"
}
],
"anchor": "I1604413732495"
},
"title": "Anatomy of atrioventricular septation complex in human 4-chambered heart with normal anatomy and in hearts with AVSDs",
"exactMatch": false,
"mediaType": "image",
"format": "png",
"links": [
{
"rel": "external",
"imageSize": "small",
"href": "https://res.cloudinary.com/eis-live/image/authenticated/t_s200/f_auto/v1/EBSCOHealth/CCMS/Dynamed/images/I1604413732495?__cld_token__=exp=1688741579~hmac=44a99de5d486cf1adf52479cb89bfb462dfdb45ee7b047571da46975583efe1d"
}
]
}
]
}
Video response when specifying small and large poster sizes
{
"_metadata": {
"queryUsed": "heart",
"pageToken": "id:rsid:98d8f67d-f8e7-4b1e-a751-7634702d6841",
"page": 1,
"pageSize": 1,
"totalPages": 33,
"totalItems": 33,
"request": {
"query": "heart",
"pageSize": 1,
"filters": [
{
"field": "pubTypeId",
"values": [
"video"
]
}
],
"fields": [
"title",
"metadata"
],
"posterSize": [
"small",
"large"
]
},
"links": [
{
"rel": "self",
"method": "post",
"href": "https://apis.ebsco.com/medsapi-dynamed/v2/content/search"
}
],
"initiatedBy": "typed-in",
"presentedAs": "result-list",
"searchTime": 7
},
"items": [
{
"id": "V1620308757808",
"contentLocations": {
"parent": [
{
"title": "Cardiovascular Physical Exam in Adults",
"pubtype": "evaluation",
"slug": "/evaluation/cardiovascular-physical-exam-in-adults"
}
],
"anchor": "V1620308757808"
},
"title": "Auscultating S1 and S2 heart sounds",
"exactMatch": false,
"mediaType": "video",
"format": "mp4",
"links": [ // This is the link to the video
{
"rel": "external",
"href": "http://media.ebsco.healthcare/eis-live/video/authenticated/f_mp4/v1/EBSCOHealth/CCMS/Dynamed/videos/V1620308757808.mp4?__cld_token__=exp=1688739530~hmac=dcf35a69d07769e5c1ff51499a8835515f9d535c4f08ee4af48d7d25d23a5a02"
},
{
"rel": "external", // Small and large poster sizes
"posterSize": "small",
"type": "poster",
"href": "http://media.ebsco.healthcare/eis-live/video/authenticated/t_s200/f_jpg/v1/EBSCOHealth/CCMS/Dynamed/videos/V1620308757808.mp4?__cld_token__=exp=1688739530~hmac=5f758b9fde164bb8f47fb10395add7c32c4a6e8ff7868ed8dc85b99a3817b194"
},
{
"rel": "external",
"posterSize": "large",
"type": "poster",
"href": "http://media.ebsco.healthcare/eis-live/video/authenticated/t_s1000/f_jpg/v1/EBSCOHealth/CCMS/Dynamed/videos/V1620308757808.mp4?__cld_token__=exp=1688739530~hmac=414e40eb371cbac3336b7e2a8dbc4b442195636b171e3a60fe28d7a8e5f827db"
}
]
}
]
}
The DynaMed/DynaMedex search endpoint can return one of the error response codes.