URI Structure

CDC’s API employs a Representational State Transfer (REST) interface. This means that method calls are made over the internet by sending HTTP GET or POST requests to the CDC REST server. Nearly any computer language can be used to communicate over HTTP with the REST server. Learn more about REST.

The CDC API uses the following URI structure:

OR

A parameter is a value passed on a URL in normal HTTP notation (first one starts with a question mark "?" and any others are separated by the ampersand character "&" e.g. http://pageurl?parameter1=1¶meter2=2 . The complete list of parameters is often referred to as the query string.

Note: In URI examples, italics indicate placeholders for variables or values. Square brackets [ ] are not included in the actual code, it's used as a convention to indicate that you must replace this area of the code with a value or variable.

Feed Request Interface

Overview

With the CDC Feed Request API, you can subscribe to news feeds on CDC topics so you can be alerted when new content is added to a topic that interests you or your organization

The feed interface has no required parameters. Calling the feed intereface with no parameters returns a feed of the entire catalog.

A future version of the CDC storefront will have a feed builder tool to help you create a feed request accurately and easily until then you can find Topic IDs by hovering

over topic names in the All Syndication Topics section of the storefront and looking at the Topic ID in the status bar of your browser or

by emailing us for assistance with feed url construction. Once you have a Topic ID (e.g. Cholera), the most basic call to the feed request interface is:

Retrieving items newer than a specific date

You can also specify a starting date for the feed. This is useful to get only the newest items on the topic. The following example returns items newer than March 1, 2010.

Specifying a feed format

You can also specify a feed format – atom (Default), rss1, rss2, or sitemap. (Note: the sitemap format is used primarily for web crawlers)

Content Request Interface

Overview

With the CDC Syndication API, you can retrieve much of CDC's vast repository of public health content. An API, or Application Programming Interface, is a way for two computer applications to talk to each other in a common language that they both understand. CDC's API provides a structured way to get CDC content in a predictable, flexible and powerful format.

CDC’s API employs a Representational State Transfer (REST) interface. This means that method calls are made over the internet by sending HTTP GET or POST requests to the CDC REST server. Nearly any computer language can be used to communicate over HTTP with the REST server. Learn more about REST.

Required Parameter

The table below details the required parameter for the Content Request REST interface (caller must provide one of the following):

Name	Code	Values	Notes
URL	url	Fully qualified CDC Mini URL in the format http://t.cdc.gov/[mini URL] For example, http://t.cdc.gov/C2T.	The CDC Mini URL of the desired syndicated content. This is the only required parameter. Learn more about CDC Mini URLs.
CATALOGID	CatalogItemId or CID	The catalog id of an item as found in a feed or XMPP payload from the system.	Found in the Id attribute of the catalogitem node in the catalog XML structure

Optional Parameters

The tables below detail the optional parameters available in the REST interface:

Content Selection Controls

Name	Code	Values	Notes
Registration ID	rid	Format is typically cs_[nnn]. For example, cs_000	Your unique Registration ID assigned to your organization during registration. The Registration ID is used to track page views and click-through from your site.
Request Class IDs	clsids	Default value 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>
Request Element IDs	elemids	Default value is null	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 that this parameter overrides class based selections.
Request XPath	xpth	Default value is null	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.

Content Processing Controls

Name	Code	Values	Notes
Strip Scripts	noscrpt	1 (default value) or 0	When this value is set to 1 (true), JavaScript is stripped from the results.
Strip Anchors	noanch	1 or 0 (default value)	When this value is set to 1 (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.
Strip Images	noimg	1 or 0 (default value)	When this value is set to 1 (true), images are stripped from the results.
Strip Comments	nocmnt	1 (default value) or 0	When this value is set to 1 (true), comments are stripped from the results.
Strip Inline Styles	nostyle	1 (default value) or 0	When this value is set to 1 (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.

Output Format Control

Name	Code	Values	Notes
JavaScript	js	1 (default value) or 0	When this value is set to 1 (true), the results will be returned as JavaScript document.write statements. When it's set to 0 (false), the results are returned as a content fragment. Setting this to true implies that you will be using the client-side (JavaScript) method as opposed to the server-side method for consuming content. Learn more about Client-side (JavaScript) vs. Server-side Methods .
JavaScript Function	jsfunction	0 (default value) or 1	If set to one, overrides the Javascript flag and returns the requested content wrapped in an Java Script function (GetContentBlock()) for use in JavaScript operations on the page.
Output Format	fmt	xhtml (default value) or xml	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.
Output Encoding	oe	UTF-8 (default value)	Defines the output format of the syndicated content. E.g. UTF-8, ISO-8859-1
Content Name Space	ns	Any combination of alpha characters. Default value is null.	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.
New Window	nw	1 (default value) or 0	When this value is set to 0 (false), links will not open into a new window. When this value is set to 1 (true), links are forcibly updated with target="_blank," which causes links to open into a new window.

Client-side (JavaScript) vs. Server-side Methods

CDC provides two different methods for retrieving syndicated pages: client-side (JavaScript) and server-side. Client-side syndication is typically implemented using JavaScript to retrieve the syndicated content when an end user accesses a syndicated page from their browser. Server-side syndication may be implemented using a variety of technologies and is a better choice if the syndicated content needs to be ingested into a Content Management System (CMS) or application. The CMS or application retrieves the content based on the schedule you set on your system. The chart below describes when to use the client-side (JavaScript) vs. server-side methods.

Method	Description
Client-side (JavaScript)	Easier to implement Syndicated content always current since browser is accessing source content every time May not be compatible when used with CMS or applications Less flexible and less control of content formatting
Server-side	Integrates better with CMS or applications More flexible and better control of content formatting Works in situations where end user may have JavaScript turned off More difficult to implement Potential lag in content updates depending on how frequently your system polls for updates

Client-side (JavaScript) Example

We'll use the following two syndication URLs as examples:

CDC H1N1 Flu Home Page

CDC H1N1 Flu - What To Do if You Get Flu-Like Symptoms

The client-side URI structure is very similar to server-side except that the JavaScript format should be set to 1 (js=1) and make sure your registration ID (rid) is set to your unique registration code (and not the cs_000 as in the examples). At the very core, this is all that's required. Normally, you would still need to write some additional code to process the JavaScript; however, CDC has already created some additional JavaScript code that makes it easier to simply copy and paste code directly to a page on your site.

In the client-side JavaScript code provided by CDC, there are references to three external JavaScript files: CDC.js, presyndicate.js and postsyndicate.js.

<script language="javascript" type="text/javascript" src="http://www.cdc.gov/jscript/presyndicate_v3.js"></script>
<script language="javascript" type="text/javascript" src="http://www.mySite.gov/cdc.js"></script>
<script language="javascript" type="text/javascript" src="http://www.cdc.gov/jscript/postsyndicate_v3.js"></script>


http://www.cdc.gov/jscript/presyndicate.js file instructions: Include this line of code on your page in the appropriate place. This JavaScript file is used to set up the appropriate variables and prepare the page to receive and process the syndicated content.

CDC.js file instructions: Create a file on your server named "cdc.js". CDC provides code as seen below that needs to be copied and pasted into that file. A reference to this file should be included in all the syndicated pages on your site. Please edit the mapping reference for each syndicated page. Enter your URL that maps to the corresponding CDC page. This file allows you to tell the system to change any embedded links to other pages you are syndicating to keep the visitor on your site. For example, if Page A has a link to Page B and you syndicate both pages, with this file, the system will replace the link to go to CDC.gov for Page B, to the URL of Page B on your site.

http://www.cdc.gov/jscript/postsyndicate.js file instructions: Include this line of code on your page in the appropriate place. This JavaScript file is used to process the received syndicated content to assure that your unique identifier is properly placed on all links, that any links to other syndicated pages on your site as mapped in the CDC.js file are properly changed and to make any other changes necessary for the content to display properly.

The full example is illustrated below:

1. Create the CDC.js file on your server, copy the code, update the registration ID and URLs

2. Copy the code to a page on your server that will host the CDC H1N1 Flu Home Page content and update the CDC.js URL

3. Copy the code to a page on your server that will host the CDC H1N1 Flu - What To Do if You Get Flu-Like Symptoms content and update the CDC.js URL

Server-side Example

For server-side ingestion (into Content Management System or application) simply use the syndication URL with the JavaScript parameter set to 0 (js=0) and make sure your registration ID (rid) is set to your unique registration code (and not the cs_000 as in the examples).

CDC H1N1 Flu Home Page

CDC H1N1 Flu - What To Do if You Get Flu-Like Symptoms

CDC Mini URL

CDC employs the use of its own URL masking service named CDC Mini URL. This is essentially a database of arbitrary IDs each matched with a destination page. This allows the CDC the flexibility to rename and/or move a destination page without affecting the URLs in the syndication code that you may have downloaded and added to your site. For example, the Mini URL for the H1N1 Flu Home page is http://t.cdc.gov/C2T. We highly recommend using the Mini URL instead of using the destination URL of http://www.cdc.gov/h1n1flu/

To find the Mini URLs for pages that you’re interested in, add those pages to Your List on this site. On the Your List page, select the Get Syndication Code button to see the syndication code with the assigned Mini URLs.

Next Steps

Getting the syndication code is very easy using CDC’s Content Syndication site. Simply follow these steps:

1. Register online to sign up for the service. You will receive a unique Registration ID that CDC uses to track metrics.
2. Browse the site to find pages you’re interested in syndicating and add those pages to Your List. You can add as many pages as you’d like.
3. When you’re finished adding syndicated pages to Your List, select Your List in the navigation bar and choose Get Syndicated Code.
4. On the Get Syndicated Code page, copy or download the code for the selected syndicated pages, follow the online instructions on that page, and add the syndicated code to your site.