API Reference

The Content Services API is RESTful. We use HTTP response codes to indicate API errors, and also use HTTP verbs which can be understood by off-the-shelf HTTP clients. JSON will be the default returned in all responses where the format is not specified, including errors.

Formats

The supported formats are JSON, JSONP, and XML.

Usage: You can specify the format as an extension (.../media.xml)
or as a querystring (...?format=xml).
If both formats are present, the extension format will be used.
For the extension format: Append the format (.jsonp) to the last resource before the querystring.

API Endpoint

https://tools.cdc.gov/api

Summary of Resource URL Patterns

/v1/resources/media
/v1/resources/media?q={STRING}
/v1/resources/media?mediatype={MEDIA_TYPE_NAME}
/v1/resources/media?title={STRING}
/v1/resources/media?topic={STRING}
/v1/resources/media?audience={STRING}
/v1/resources/media?language={STRING}
/v1/resources/media/{ID}?showchildlevel={POSITIVE_INTEGER}
/v1/resources/media/{ID}?showparentlevel={POSITIVE_INTEGER}
/v1/resources/media?ttl={POSITIVE_INTEGER}
/v1/resources/media/{MEDIA_ID}
/v1/resources/media?sort={ATTRIBUTE_NAME}
/v1/resources/media?sort=—{ATTRIBUTE_NAME}
/v1/resources/media?max={POSITIVE_INTEGER}&pagenum={POSITIVE_INTEGER}
/v1/resources/media?max={POSITIVE_INTEGER}&offset={POSITIVE_INTEGER}
/v1/resources/media?max={POSITIVE_INTEGER}&offset={POSITIVE_INTEGER}&pagenum={POSITIVE_INTEGER}
/v1/resources/media/{MEDIA_ID}/embed
/v1/resources/media/{MEDIA_ID}/syndicate
/v1/resources/media/{MEDIA_ID}/content
/v1/resources/mediatypes
/v1/resources/topics
/v1/resources/audiences
/v1/resources/languages
/v1/resources/organizations
/v1/resources/organizationtypes

Response

The API returns the result of ALL requests using the same data structure.

Attributes

meta: Contains metadata about the response object.
results: An array of objects that contains the data.

Media

Represents all the multi-media types (HTML, Images, Buttons, Badges, Widgets, Infographics, etc.) in the Content Services System.

Attributes

mediaId: string
title: string
description: string
mediaType: string
tags: topic, audience
sourceUrl: string
targetUrl: string
language: string
thumbnailUrl: string
rating: string
ratingCount: string
ratingCommentCount: string
embedCode: string
attribution: string
persistentUrl: string or null
status: string, value is "Published"
datePublished: string
dateModified: string
childCount: positive integer or zero
children: object or null
parentCount: positive integer or zero
parents: object or null
sourceCode: string
domainName: string or null
owningOrgId: positive integer or null
owningOrgName: string or null
maintainingOrgId: positive integer or null
maintainingOrgName: string or null

{
    "mediaId": "16",
    "title": "Tobacco Use - Winnable Battles",
    "description": null,
    "mediaType": "HTML",
    "tags": {
        "topic": [
          {
            "id": 10,
            "name": "Smoking Cessation"
          }
        ]
    },
    "sourceUrl": "http://www.cdc.gov/winnablebattles/Tobacco/index.html",
    "targetUrl": "http://www.cdc.gov/winnablebattles/Tobacco/index.html",
    "language": English,
    "thumbnailUrl": "https://tools.cdc.gov/api/v1/resources/media/16/thumbnail",
    "rating": null,
    "ratingCount": null,
    "ratingCommentCount": null,
    "embedCode": "",
    "attribution": null,
    "persistentUrl": null,
    "status": "Published",
    "datePublished": "2013-04-01 12:00:00",
    "dateModified": "2013-04-01 12:00:00",
    "childCount": 0,
    "children": null,
    "parentCount": 0,
    "sourceCode": "Food and Drug Administration",
    "domainName": "http://www.fda.gov/",
    "owningOrgId": null,
    "owningOrgName": null,
    "maintainingOrgId": null,
    "maintainingOrgName": null
}

Search

Retrieve media available in the Content Services system.

Parameters

q: optional, full-text search Full-Text search on topic, title, and description. For exact search used quotation marks (ex: "exact phrase to match").
mediatype: optional Used one media type name or multiple media types separated by comma.
title: optional Full-Text search on title.
topic: optional Full-Text search on topic.
audience: optional Full-Text search on audience.
language: optional, CSV
showChildLevel: positive integer Returns the descendant items to the specified level in the children attribute of a media item.
showParentLevel: positive integer Returns the ancestor items to the specified level in the parents attribute of a media item.
ttl: optional, maximum is 900 Time to live (ttl) is the number of seconds to cache a request.

Returns

Returns the media object in the results of the response.


      List of Media:
GET https://tools.cdc.gov/api/v1/resources/media      
      Full-Text search:
GET https://tools.cdc.gov/api/v1/resources/media?q={STRING}
      MediaType search:
GET https://tools.cdc.gov/api/v1/resources/media?mediatype={MEDIA_TYPE_NAME}
      Title search:
GET https://tools.cdc.gov/api/v1/resources/media?title={STRING}
      Topic search:
GET https://tools.cdc.gov/api/v1/resources/media?topic={STRING}
      Audience search:
GET https://tools.cdc.gov/api/v1/resources/media?audience={STRING}
      Language search:
GET https://tools.cdc.gov/api/v1/resources/media?language={STRING}
      Show Child Level search:
GET https://tools.cdc.gov/api/v1/resources/media/{ID}?showchildlevel={POSITIVE_INTEGER}
      Show Parent Level search:
GET https://tools.cdc.gov/api/v1/resources/media/{ID}?showparentlevel={POSITIVE_INTEGER}
      Cache search:
GET https://tools.cdc.gov/api/v1/resources/media?ttl={POSITIVE_INTEGER}

Retrieve media by id

Retrieves the details of a media that can be syndicated.

Parameter

id: required The identifier of the media to be retrieved.

Returns

Returns the media object in the results of the response if a valid identifier was provided.

GET https://tools.cdc.gov/api/v1/resources/media/{MEDIA_ID}

Sort

Order the items returned using the attribute names of the media object.

Ascending is the default sort direction. The minus sign (—) is used to denote Descending.

Parameter

sort: optional, default is ASC The attribute name to sort by. DESC: use the minus sign (—) before the attribute name.

Returns

Returns the media object in the results of the response.


    ASC:
GET https://tools.cdc.gov/api/v1/resources/media?sort={ATTRIBUTE_NAME}
    DESC:
GET https://tools.cdc.gov/api/v1/resources/media?sort=—{ATTRIBUTE_NAME}

Pagination

Divide the returned items into multiple result sets (pages).

The pagination object in the response (meta) contains the URLs for the current, previous, and next page.

Parameters

max: optional, default is 100 A limit on the number of items return per page.
pagenum: optional, default is 1 The page to return.
offset: optional, default is 0 The number of records to skip in the list of returned items.

Returns

Returns the media object in the results of the response.


    OPTION 1:
GET https://tools.cdc.gov/api/v1/resources/media?max={POSITIVE_INTEGER}&pagenum={POSITIVE_INTEGER}    
    OPTION 2:
GET https://tools.cdc.gov/api/v1/resources/media?max={POSITIVE_INTEGER}&offset={POSITIVE_INTEGER}
    OPTION 3:
GET https://tools.cdc.gov/api/v1/resources/media?max={POSITIVE_INTEGER}&offset={POSITIVE_INTEGER}&pagenum={POSITIVE_INTEGER}

Embed Code

Retrieve the embedded code used to display and process the syndicated HTML content of a media.

Parameters

All Syndication parameters are valid.

includeJq: optional, default is true Include jQuery. When this value is set to “false”, the reference to the default jQuery file is not included.
jqSrc: optional jQuery Source. Absolute or relative path to the jQuery source file (.js) that you wish to include.
jsPluginSrc: optional Javascript Plugin Source. Absolute or relative path to the jQuery source file (.js) that you wish to use to process the syndicated content.
cssHref: optional, CSV CSS Hypertext Reference. Absolute or relative path to the stylesheets (.css) that you wish to include.

GET https://tools.cdc.gov/api/v1/resources/media/{MEDIA_ID}/embed

"results": "{HTML Embed Code}"

Syndication

Retrieve the syndicated HTML content of a media.

Parameters

stripScript: optional, default is true When this value is set to “true”, JavaScript is stripped from the results.
stripAnchor: optional, default is false When this value is set to “true”, anchor tags are stripped from the results, converting links into regular text. An Anchor is a HTML or XHTML element used to hyperlink to another document, or another location on the current document.
stripImage: optional, default is false When this value is set to “true”, images are stripped from the results.
stripComment: optional, default is true When this value is set to “true”, comments are stripped from the results.
stripStyle: optional, default is true When this value is set to “true”, inline styles are stripped from the results. An inline style is a style that is applied to an HTML or XHTML element as an attribute of that element.
clsids: optional, default is syndicate A comma delimited list of class IDs to retrieve from the given URL. A class ID is an attribute of an xhtml node normally used to determine the display characteristics of that element in an HTML browser. Used here as a method of selecting content from a source page.
E.g. <div class="syndicate"></div>
elemids: optional A comma delimited list of elements to retrieve from the given URL. An element ID is an attribute of an xhtml node normally used to identify the element for use in programming or for convenience. Used here as a method of selecting content from a source page.
E.g. <div id="content-main"></div>
Note: This parameter overrides class based selections.
xpath: optional An xpath statement defining what should be retrieved from the URL and returned in the result. XPath is a hierarchical/navigation XML programming tool used for location and selecting XML elements in XML documents. Used here as a method of selecting content from a source XHTML page. Note that this parameter overrides both element and class based selections.
E.g. xpath=//html:body/descendant::html:*[@id='moreInfo']
oe: optional, default is UTF-8 Output encoding. Defines the output format of the syndicated content.
E.g. utf-8, iso-8859-1
of: optional, default is xhtml Output format. XHTML (Extensible Hypertext Markup Language) is a spinoff of the hypertext markup language (HTML) used for creating Web pages. It is based on the HTML 4.0 syntax, but has been modified to follow the guidelines of XML. XML (EXtensible Markup Language) is open standard for describing data from the W3C. It is used for defining data elements on a Web page and business-to-business documents. XML uses a similar tag structure as HTML; however, whereas HTML defines how elements are displayed, XML defines what those elements contain.
E.g. xhtml or xml
ns: optional, default is cdc Namespace. Used to decorate (prefix) the tags and ids in the results to prevent conflict with existing host page elements. Must contain only upper or lower case letters. An underscore character will be appended by the service.
nw: optional, default is true New window. When this value is set to “false”, links will not open into a new window. When this value is set to “true”, links are forcibly updated with target="_blank," which causes links to open into a new window.
w: optional Width. Set the width of various media types.
h: optional Height. Set the height of various media types.

GET https://tools.cdc.gov/api/v1/resources/media/{MEDIA_ID}/syndicate

"results": {
  "mediaId": 64,
  "mediaType": "HTML",
  "sourceUrl": "http://www.cdc.gov/mmwr/preview/mmwrhtml/mm6120a3.htm",
  "targetUrl": "http://www.cdc.gov/mmwr/preview/mmwrhtml/mm6120a3.htm",
  "title": "Smoking is bad, 1998–2010",
  "description": "",
  "content": "{SYNDICATED HTML}"
}

Content

Returns Syndication content as defined by the parameters for a Media Type.

Parameters

Includes all Syndication Parameters.

GET https://tools.cdc.gov/api/v1/resources/media/{MEDIA_ID}/content

Media Types

List of the available media types.

Attributes

name: string
description: string
displayOrdinal: positive integerThe order of the object in the database.

GET https://tools.cdc.gov/api/v1/resources/mediatypes

"results": [
  {
    "name": "Video",
    "description": "Videos",
    "displayOrdinal": 2
  },
  {
    "name": "HTML",
    "description": "HTML Content",
    "displayOrdinal": 3
  },
  {...}  
]

Topics

List of the available topics.

Parameters

language: string, CSV, default is English
showChild: boolean, default is false Return sub-topics in the items attribute when set to true.
mediaType: string Filter topics using media type.

Attributes

id: positive integer
name: string
description: string
language: string
mediaUsageCount: positive integer, The number of media items tagged.
displayOrdinal: positive integerThe order of the object in the database.
items: array of objectsContains the same attributes as the parent object.

GET https://tools.cdc.gov/api/v1/resources/topics

"results": [
  {
    "id": 1,
    "name": "Diseases &amp; Conditions",
    "description": "Diseases &amp; Conditions",   
    "language": "English", 
    "mediaUsageCount": 267,
    "displayOrdinal": 0,
    "items": [ ]
  },
  {...}      
]

Audiences

List of the available audiences.

Parameters

language: string, CSV, default is English

Attributes

id: positive integer
name: string
description: string
language: string
mediaUsageCount: positive integer, or null The number of media items tagged.
displayOrdinal: positive integerThe order of the object in the database.
items: an array of objectsContains the same attributes as the parent object.

GET https://tools.cdc.gov/api/v1/resources/audiences

"results": [
  {
    "id": 25,
    "name": "Parents",
    "description": null,
    "language": "English",
    "mediaUsageCount": 1,
    "displayOrdinal": 0,
    "items": [ ]
  },
  {...}  
]

Languages

List of the available Languages.

Attributes

name: string
description: string
displayOrdinal: positive integerThe order of the object in the database.

GET https://tools.cdc.gov/api/v1/resources/languages

"results": [
  {
    "name": "English",
    "description": "English (US)",
    "displayOrdinal": 0
  },
  {...}  
]

Organizations

List of the available Organizations.

Attributes

id: positive integer
name: string
website: array of objects
type: string
typeOther: string
description: string
address: string
addressContinued: string
city: string
stateProvince: string
postalCode: string
county: string
country: string

GET https://tools.cdc.gov/api/v1/resources/organizations

"results": [
  {
    "id": 356,
    "name": "CDC",
    "website": [
      {
        "url": "http://m.cdc.gov",
        "isDefault": false
      },
      {
        "url": "http://www.cdc.gov"
        "isDefault": true
      }
    ],
    "type": "U.S. Federal Government",
    "typeOther": null,
    "description": "U.S. Federal Government",
    "address": "Clifton Rd.",
    "addressContinued": null,
    "city": "Atlanta",
    "stateProvince": "GA",
    "postalCode": "30333",
    "county": "Fulton",
    "country": "US"
  },
  {...}  
]

Organization Types

List of the available Organization Types.

Attributes

type: string
description: string
displayOrdinal: positive integerThe order of the object in the database.

GET https://tools.cdc.gov/api/v1/resources/organizationtypes

"results": [
  {
    "type": "U.S. Federal Government",
    "description": "U.S. Federal Government",
    "displayOrdinal": 1
  },
  {...}  
]

API Reference

Formats

API Endpoint

Summary of Resource URL Patterns

Response

Attributes

Meta

Media

Attributes

Search

Parameters

Returns

List of Media:

Full-Text search:

MediaType search:

Title search:

Topic search:

Audience search:

Language search:

Show Child Level search:

Show Parent Level search:

Cache search:

Retrieve media by id

Parameter

Returns

Sort

Parameter

Returns

ASC:

DESC:

Pagination

Parameters

Returns

OPTION 1:

OPTION 2:

OPTION 3:

Embed Code

Parameters

Syndication

Parameters

Content

Parameters

Media Types

Attributes

Topics

Parameters

Attributes

Audiences

Parameters

Attributes

Languages

Attributes

Organizations

Attributes

Organization Types

Attributes