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

/v2/resources/media
/v2/resources/media?q={STRING}
/v2/resources/media?mediatypes={MEDIA_TYPE_NAME}
/v2/resources/media?name={STRING}
/v2/resources/media?topic={STRING}
/v2/resources/media?topicids={CSV}
/v2/resources/media?audience={STRING}
/v2/resources/media?tags={STRING}
/v2/resources/media?tagtypes={STRING}
/v2/resources/media?languagename={STRING}
/v2/resources/media?languageisocode={STRING}
/v2/resources/media?sourcename={STRING}
/v2/resources/media?sourceacronym={STRING}
/v2/resources/media/{ID}?showchildlevel={POSITIVE_INTEGER}
/v2/resources/media/{ID}?showparentlevel={POSITIVE_INTEGER}
/v2/resources/media?ttl={POSITIVE_INTEGER}
/v2/resources/media/{MEDIA_ID}
/v2/resources/media?sort={ATTRIBUTE_NAME}
/v2/resources/media?sort=—{ATTRIBUTE_NAME}
/v2/resources/media?sort={ATTRIBUTE_NAME}&order=ASC
/v2/resources/media?sort={ATTRIBUTE_NAME}&order=DESC
/v2/resources/media?max={POSITIVE_INTEGER}&pagenum={POSITIVE_INTEGER}
/v2/resources/media?max={POSITIVE_INTEGER}&offset={POSITIVE_INTEGER}
/v2/resources/media?max={POSITIVE_INTEGER}&offset={POSITIVE_INTEGER}&pagenum={POSITIVE_INTEGER}
/v2/resources/media/{MEDIA_ID}/embed
/v2/resources/media/{MEDIA_ID}/syndicate
/v2/resources/media/{MEDIA_ID}/content
/v2/resources/mediatypes
/v2/resources/topics
/v2/resources/audiences
/v2/resources/languages
/v2/resources/organizations
/v2/resources/organizationtypes
/v2/resources/sources

Response

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

All DateTime fields are in the ISO 8601 format: yyyy-MM-ddTHH:mm:ssZ

Attributes

meta: Contains metadata about the response object.
results: 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

id: positive integer
name: string
description: string
mediaType: string
language: language
tags: array of objects
campaigns: array of objects
source: source
attribution: string
domainName: string
owningOrgName: string
owningOrgId: positive integer
maintainingOrgName: string
maintainingOrgId: positive integer
sourceUrl: string
targetUrl: string
persistentUrl: string
thumbnailUrl: string
alternateImages: array of objects
alternateText: string
noScriptText: string
featuredText: string
author: string
length: string
size: positive integer
height: positive integer
width: positive integer
embedCode: string
childCount: positive integer
children: array of objects
parentCount: positive integer
parents: array of objects
rating: string
ratingCount: string
ratingCommentCount: string
status: string
datePublished: string
dateModified: string
dateContentAuthored: string
dateContentUpdated: string
dateContentPublished: string
dateContentReviewed: string
dateSyndicationCaptured: string
dateSyndicationUpdated: string
dateSyndicationVisible: string
extendedAttributes: array of objects
extension: object

{
    "id": 16,
    "name": "Tobacco Use - Winnable Battles",
    "description": null,
    "mediaType": "HTML",
    "language": {
        "name": "English",
        "isoCode": "eng"
    },
    "tags": [
        {
          "id": 10,
          "name": "Smoking Cessation",
          "language": "English",
          "type": "Topic"
        }     
    ],  
    "geoTags": [
        {
          "name": "Bleckley County",
          "countryCode": "US",
          "geoNameId": 4183415,
          "parentId": 4197000,
          "latitude": 32.43444,
          "longitude": -83.32784,
          "timezone": "America/New_York",
          "admin1Code": "GA"
        }     
    ],
    "campaigns": [],
    "source": {
        "name": "Centers for Disease Control and Prevention",
        "acronym": "CDC",
        "websiteUrl": null,
        "largeLogoUrl": null,
        "smallLogoUrl": null
    },
    "attribution": null,    
    "domainName": "http://www.fda.gov/",
    "owningOrgName": null,
    "owningOrgId": null,
    "maintainingOrgName": null,
    "maintainingOrgId": null,
    "sourceUrl": "http://www.cdc.gov/winnablebattles/Tobacco/index.html",
    "targetUrl": "http://www.cdc.gov/winnablebattles/Tobacco/index.html",    
    "persistentUrl": null,    
    "thumbnailUrl": "https://tools.cdc.gov/api/v2/resources/media/16/thumbnail",
    "alternateImages": [
      {
        "id": 4,
        "name": "Facebook",
        "width": 155,
        "height": 84,
        "url": "https://tools.cdc.gov/api/v2/resources/links/4.png"
      },
      {...}
    ],
    "alternateText": null,
    "noScriptText": null,
    "featuredText": null,
    "embedCode": null,
    "author": null,
    "length": "",
    "size": null,
    "height": null,
    "width": null,      
    "childCount": 0,
    "children": [],
    "parentCount": 0,
    "parents": [],
    "rating": null,
    "ratingCount": null,
    "ratingCommentCount": null,
    "status": "Published",
    "datePublished": "2014-03-18T20:30:00Z",
    "dateModified": "2013-04-01 12:00:00",
    "dateContentAuthored": null,
    "dateContentUpdated": null,
    "dateContentPublished": null,
    "dateContentReviewed": null,
    "dateSyndicationCaptured": null,
    "dateSyndicationUpdated": null,
    "dateSyndicationVisible": null,
    "extendedAttributes": [],
    "extension": {}
}

Search

Retrieve media available in the Content Services system.

Parameters

All parameters are optional. All valid Date parameters are in the ISO 8601 format: yyyy-MM-ddTHH:mm:ssZ

fields: string, CSV
first-level{second-level} You can choose the fields you want returned with the "fields" parameter. This is really useful for reducing the payload of your JSON & JSONP API calls.
Ex: ...?fields=id,mediatype,tags{name,type}
q: string Searches topic, name, and description. For an exact match use quotation marks (ex: "exact phrase to match").
mediaTypes: string, CSV
name: string
nameContains: string
description: string
descriptionContains: string
topic: string
topicIds: positive integer, CSV Enter valid Sub-topic Ids.
audience: string
languageName: string, CSV
languageIsoCode: string, CSV
sourceName: string
sourceNameContains: string
sourceAcronym: string
sourceAcronymContains: string
sourceUrl: string
sourceUrlContains: string
showChildLevel: positive integer Return the descendant items to the specified level in the children attribute of a media item.
showParentLevel: positive integer Return the ancestor items to the specified level in the parents attribute of a media item.
geoName: string Searches the name field of the geoTags object.
geoNameId: positive integer Searches the geoNameId field of the geoTags object.
geoParentId: positive integer Searches the geoParentId field of the geoTags object.
countryCode: string Searches the countryCode field of the geoTags object.
latitude: double Searches the latitude field of the geoTags object.
longitude: double Searches the longitude field of the geoTags object.
dateContentAuthored: string Return items that are equal to the year, month and day.
contentAuthoredSinceDate: string Return items that are equal to greater than the year, month and day.
contentAuthoredBeforeDate: string Return items that are less than the year, month and day.
contentAuthoredInRange: string, CSV Return items that are equal to and between the year, month and day ranges.
dateContentUpdated: string Return items that are equal to the year, month and day.
contentUpdatedSinceDate: string Return items that are equal to greater than the year, month and day.
contentUpdatedBeforeDate: string Return items that are less than the year, month and day.
contentUpdatedInRange: string, CSV Return items that are equal to and between the year, month and day ranges.
dateContentPublished: string Return items that are equal to the year, month and day.
contentPublishedSinceDate: string Return items that are equal to greater than the year, month and day.
contentPublishedBeforeDate: string Return items that are less than the year, month and day.
contentPublishedInRange: string, CSV Return items that are equal to and between the year, month and day ranges.
dateContentReviewed: string Return items that are equal to the year, month and day.
contentReviewedSinceDate: string Return items that are equal to greater than the year, month and day.
contentReviewedBeforeDate: string Return items that are less than the year, month and day.
contentReviewedInRange: string, CSV Return items that are equal to and between the year, month and day ranges.
dateSyndicationCaptured: string Return items that are equal to the year, month and day.
syndicationCapturedSinceDate: string Return items that are equal to greater than the year, month and day.
syndicationCapturedBeforeDate: string Return items that are less than the year, month and day.
syndicationCapturedInRange: string, CSV Return items that are equal to and between the year, month and day ranges.
dateSyndicationUpdated: string Return items that are equal to the year, month and day.
syndicationUpdatedSinceDate: string Return items that are equal to greater than the year, month and day.
syndicationUpdatedBeforeDate: string Return items that are less than the year, month and day.
syndicationUpdatedInRange: string, CSV Return items that are equal to and between the year, month and day ranges.
dateSyndicationVisible: string Return items that are equal to the year, month and day.
syndicationVisibleSinceDate: string Return items that are equal to greater than the year, month and day.
syndicationVisibleBeforeDate: string Return items that are less than the year, month and day.
syndicationVisibleInRange: string, CSV Return items that are equal to and between the year, month and day ranges.

Returns

Returns the media object in the results of the response.


      List of Media:
GET https://tools.cdc.gov/api/v2/resources/media      
      Full-Text search:
GET https://tools.cdc.gov/api/v2/resources/media?q={STRING}
      MediaType search:
GET https://tools.cdc.gov/api/v2/resources/media?mediatypes={MEDIA_TYPE_NAME}
      Name search:
GET https://tools.cdc.gov/api/v2/resources/media?name={STRING}
      Topic search:
GET https://tools.cdc.gov/api/v2/resources/media?topic={STRING}
      Topic Id search:
GET https://tools.cdc.gov/api/v2/resources/media?topicids={CSV}
      Audience search:
GET https://tools.cdc.gov/api/v2/resources/media?audience={STRING}
      Language Name search:
GET https://tools.cdc.gov/api/v2/resources/media?languagename={STRING}
      Language IsoCode search:
GET https://tools.cdc.gov/api/v2/resources/media?languageisocode={STRING}
      Source Name search:
GET https://tools.cdc.gov/api/v2/resources/media?sourcename={STRING}
      Source Acronym search:
GET https://tools.cdc.gov/api/v2/resources/media?sourceacronym={STRING}
      Show Child Level search:
GET https://tools.cdc.gov/api/v2/resources/media/{ID}?showchildlevel={POSITIVE_INTEGER}
      Show Parent Level search:
GET https://tools.cdc.gov/api/v2/resources/media/{ID}?showparentlevel={POSITIVE_INTEGER}
      Cache search:
GET https://tools.cdc.gov/api/v2/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/v2/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: multiple column (CSV), default is ASC DESC: use the minus sign (—) before the attribute name.
order: single column, ASC or DESC

Returns

Returns the media object in the results of the response.


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

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/v2/resources/media?max={POSITIVE_INTEGER}&pagenum={POSITIVE_INTEGER}    
    OPTION 2:
GET https://tools.cdc.gov/api/v2/resources/media?max={POSITIVE_INTEGER}&offset={POSITIVE_INTEGER}
    OPTION 3:
GET https://tools.cdc.gov/api/v2/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.

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

"results": "{HTML Embed Code}"

Syndication

Retrieve the syndicated HTML content of a media.

Parameters

stripScripts: optional, default is true When this value is set to “true”, JavaScript is stripped from the results.
stripAnchors: 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.
stripImages: optional, default is false When this value is set to “true”, images are stripped from the results.
stripComments: optional, default is true When this value is set to “true”, comments are stripped from the results.
stripStyles: 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.
stripBreaks: optional, default is false When this value is set to “true”, br elements are stripped from the results.
cssClasses: 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>
ids: 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/v2/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",
  "name": "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/v2/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/v2/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/v2/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 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/v2/resources/audiences

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

Tag Types

List of the available tag types.

Attributes

id: positive integer
name: string
description: string

GET https://tools.cdc.gov/api/v2/resources/tagtypes

"results": [
  {
    "id": 1,
    "name": "Topic",
    "description": "Topic"  
  },
  {
    "id": 2,
    "name": "Audience",
    "description": "Audience"   
  },
  {...}      
]

Languages

List of the available Languages.

Attributes

name: string
isoCode: string

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

"results": [
  {
    "name": "English",
    "isoCode": "eng"
  },
  {...}  
]

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/v2/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/v2/resources/organizationtypes

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

Sources

List of the available Sources.

Attributes

name: string
acronym: string
websiteUrl: string
largeLogoUrl: string
smallLogoUrl: string

GET https://tools.cdc.gov/api/v2/resources/sources

"results": [
  {
    "name": "Centers for Disease Control and Prevention",
    "acronym": "CDC",
    "websiteUrl": "http://www.cdc.gov",
    "largeLogoUrl": null,
    "smallLogoUrl": null,
    {...},
    {...}
  }
]

API Changes

Only "backwards-incompatible" changes to the API are reflected.

What changes are consider to be “backwards-compatible”?

Adding new API resources.
Adding new optional request parameters to existing API methods.
Adding new properties to existing API responses.
Changing the order of properties in existing API responses.

Media

Details:

Changed "mediaId" string to "id" integer.
Changed "title" to "name".
Changed "language" string to language object.
Changed "sourceCode" string to source object
Changed Date format "yyyy-MM-dd HH:mm:ss" to "yyyy-MM-ddTHH:mm:ssZ"
Changed mediaType parameter to mediaTypes.
Changed language parameter to languageName.

{
    "id": 16,
    "language": {
        "name": "English",
        "isoCode": "eng"
    },
    "source": {
        "name": "Centers for Disease Control and Prevention",
        "acronym": "CDC",
        "websiteUrl": null,
        "largeLogoUrl": null,
        "smallLogoUrl": null
    },
    "datePublished": "2013-04-01T12:00:00Z",
    ...
}

Syndication

Details:

Changed string "mediaId" to integer on the response object.
Changed "title" to "name".
Changed stripAnchor parameter to stripAnchors.
Changed stripImage parameter to stripImages.
Changed stripStyle parameter to stripStyles.
Changed clsids parameter to cssClasses.
Changed elemids parameter to ids.

Languages

Details:

Removed the "displayOrdinal" attribute from the response object.
Removed the "description" attribute from the response object.

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:

Name search:

Topic search:

Topic Id search:

Audience search:

Language Name search:

Language IsoCode search:

Source Name search:

Source Acronym search:

Show Child Level search:

Show Parent Level search:

Cache search:

Retrieve media by id

Parameter

Returns

Sort

Parameter

Returns

ASC:

DESC:

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

Tags

Parameters

Attributes

Retrieve tag by id

Parameter

Returns

Retrieve media by tag id

Parameter

Returns

Retrieve related tags by id.

Parameter

Returns

Tag Types

Attributes

Languages

Attributes

Organizations

Attributes

Organization Types

Attributes

Sources

Attributes

API Changes

Media