API

METHODS

REFERENCES

 
 

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.
 
Meta
status
positive integer 200 OK - Everything worked as expected. 400 Bad Request - Often missing a required parameter. 500 Server errors - something went wrong on our end.
message
array of objects Used to display information about each request that is related to the status (meta).
resultSet
Information about the result.
pagination
Paging information about the data returned.
{ "meta": { "status": 200, "message": [ { "type": "Error", "code": "", "id": "", "userMessage": "", "developerMessage": "" } ], "resultSet": { "id": "becbbe39-7308-422d-a567-690d588c4600" }, "pagination": { "total": 94, "count": 20, "max": 20, "offset": 20, "pageNum": 1, "totalPages": 5, "sort": "datePublished DESC, name ASC", "currentUrl": "https://tools.cdc.gov/api/v2/resources/media?mediatype=html&max=20&offset=20&pagenum=3", "previousUrl": null, "nextUrl": null } }, "results": [ {...}, {...} ] }
 

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": [ ] }, {...} ]
 

Tags

List of the available tags.

Parameters
language
string, CSV
name
string, CSV Return tag(s) matching the supplied name(s).
nameContains
string Return tags which contain the supplied partial name.
mediaId
positive integer Return tags associated with the supplied media id.
typeId
positive integer Return tags belonging to the supplied tag type id.
typeName
string Return tags belonging to the supplied tag type name.
Attributes
id
positive integer
name
string
language
string
type
string
GET https://tools.cdc.gov/api/v2/resources/tags "results": [ { "id": 1, "name": "Diseases &amp; Conditions", "language": "English", "type": "Topic" }, {...} ]
 

Retrieve tag by id

Retrieves a tag object using its id.

Parameter
id
required The identifier of the tag to be retrieved.
Returns

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

GET https://tools.cdc.gov/api/v2/resources/tags/{TAG_ID}
 

Retrieve media by tag id

Retrieves media objects using a tag id.

Parameter
id
required The identifier of the tag 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/tags/{TAG_ID}/media
 

Retrieve related tags by id.

Retrieves tag objects related to another tag.

Parameter
id
required The identifier of the tag to be retrieved.
Returns

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

GET https://tools.cdc.gov/api/v2/resources/tags/{TAG_ID}/related
 

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.