HHS' 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 HHS REST server. Nearly any computer language can be used to communicate over HTTP with the REST server.
The HHS API uses the following URI structure:
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
With the HHS Feed Request API, you can subscribe to news feeds on HHS topics so you can be alerted when new content is added to a topic that interests you or your organization. The feed interface requires a feed ID, which is generated on a per-feed basis in the storefront
Once you have a topicid (e.g. Cholera), the most basic call to the feed request interface is:
Retrieving items from the last 30 days (limit 250)
Retrieving the 20 newest items
Retrieving the 20 most popular items (by likes)
Specifying a feed format
You can also specify a feed format – rss2 (Default), rss1, atom.
Content Request Interface
With the HHS Syndication API, you can retrieve much of HHS' 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. HHS' API provides a structured way to get HHS content in a predictable, flexible and powerful format.
HHS' 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 HHS REST server. Nearly any computer language can be used to communicate over HTTP with the REST server. Learn more about REST.
The table below details the required parameter for the Content Request REST interface (caller must provide one of the following):
|URL||url||Fully qualified HHS Tiny URL in the format http://tiny.HHS.gov/[UID] For example. http://tiny.hhs.gov/c2T.||The HHS Tiny URL of the desired syndicated content. This is the only required parameter.|
The tables below detail the optional parameters available in the REST interface:
Content Selection Controls
|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
|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
|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.|
HHS Tiny URL
HHS employs the use of its own URL masking service named HHS Tiny URL. This is essentially a database of arbitrary IDs each matched with a destination page. This allows the HHS 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 Tiny URL for the H1N1 Flu Home page is http://tiny.HHS.gov/C2T. We highly recommend using the Tiny URL instead of using the destination URL of http://www.HHS.gov/h1n1Flu
To find the Tiny 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 Tiny URLs.
Getting the syndication code is very easy using HHS' Content Syndication site. Simply follow these steps:
- Register online to sign up for the service. You will receive a unique Registration ID that HHS uses to track metrics.
- 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.
- When you’re finished adding syndicated pages to Your List, select Your List in the navigation bar and choose Get Syndicated Code.
- 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.
Syndication Application Version: