API Documentation

URI Structure

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&parameter2=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 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

Overview

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.

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 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.

Optional Parameters

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

Content Selection Controls

Name Code Values Notes
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
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.

Next Steps

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: