U.S. Department of Health and Human Services

Menu

How to Use the
healthfinder.gov API

What Is an Application Programming Interface (API)?

  • An API is a method to open up and allow access to specific content or functionality from within an application.
  • It allows other developers or organizations to use specific functionality, usually to build or produce new functionality.
  • An API has specific rules and requirements that allow users to properly access the content or functionality.

To learn more about APIs:

How to Use the healthfinder.gov API

  • The API will provide the latest version of the healthfinder.gov content in English and Spanish.
  • The API requires an access key. To obtain an access key, please register to create an account.
  • The API can be accessed on an as-needed basis. There is no limit on how often you can access it. However, some safeguards will lock out a query request, if there are too many requests in a specific amount of time.
  • The healthfinder.gov feed is provided in XML and JSON formats.

Examples of Health Topics A to Z API:

Examples of myhealthfinder API:

API Parameters

Required Parameter: To use the API, you need a valid access key that links to your registered account in the system. Sign up for an API account here to get your access key.

  • api_key = the unique access key for each registered organization using the site

Spanish Parameter (optional): To access Spanish content in the API, append the following parameter to the end of the query string.

  • Please Note: There is not a “one to one” corresponding English to Spanish content between keywords, Categories, Topics, and Tools. Unfortunately, the following parameter cannot just be added to the end of an English query and generate the same exact query in Spanish.
  • lang = es: will query the Spanish version of the Health Topic
    http://healthfinder.gov/developer/Search.xml?api_key=demo_api_key&topicID=9&lang=es

Return Type (optional): To change the result from XML to JSON, change the extension of the API request from xml to JSON.

Callback (optional): This parameter sets the callback function for JSON requests. It allows cross-domain ajax request to be made.

Health Topics A to Z API Primary Parameters

At least one of the parameters below must be included in the Health Topics A to Z API for it to function correctly.

All Topics and Tools: To return all of the topics and tools (everything) in the system, use the following code.

Keyword (also known as content or key phrases): When this parameter is used, the system is expecting at least one or multiple words to use to query the database. To search using multiple keywords, enter a space between each term.

CategoryID: The API is expecting a number value that matches one of the Category IDs in the database. When Category is used, all of the topics within the category will be returned.

TopicID: The API is expecting a number value that matches one of the Topic IDs in the database.

ToolID: The API is expecting a number value that matches one of the Tool IDs in the database.

myhealthfinder API Primary Parameters

The 2 required parameters below must be included in the myhealthfinder API for it to function correctly. The optional parameters may be included for additional filtering.

Age (required): The API is expecting a number value containing the age recommendations to be returned.

Gender (required): The API is expecting a string value that matches one of the following values:

  • Male
  • Female
  • Hombre
  • Mujer

Pregnant (optional): The API is expecting a boolean value of zero for false or 1 for true. This parameter is only accepted for females age 11 and up.

  • 0 = false
  • 1 = true

Who (optional): The API is expecting a string value that matches one of the following values. The “who” parameter modifies the messages based on the type of person the content is requested for.

  • Me
  • Someone Else
  • Child