Primary tabs

Data API

Healthdata.gov is rolling out APIs for the data in datasets in the Healthdata.gov catalog. This Data API provides application developers with search and query capabilities for data in API-enabled datasets. The Data API promotes the rapid development of apps around health data.

The Data API described below supplements the bulk data downloads available for datasets listed in the catalog. Also available is the Catalog API which provides programmatic access to the complete metadata in the Healthdata.gov data catalog.

The Data API is currently enabled for three datasets:

Questions about the Data API can be sent to the HealthDataGov Google Group.

Examples

Here are some examples of what you can do with the Data API:

TXT4Tots

The TXT4Tots Message Library datasets provide recommended text for age-appropriate nutrition and physical activity reminders. Use the Data API to build an app that sends text messages to caregivers with short reminders appropriate to the age of their child. The app can query the Data API for the next message to send, given the child’s age.

The following example uses the ‘curl’ command-line tool to demonstrate this API query. The query parameters are passed in POST request in JSON format.

curl http://hub.Healthdata.gov/api/action/datastore_search --data-urlencode '
{
  "resource_id": "abed461e-3eb0-4596-9e1e-3a45817e71c4",
  "filters": {
    "childsageinweeks": 97
  }
}'

The JSON result of the query is:

{
  "help": ...,
  "result": {
    "_links": {
      "next": "/api/action/datastore_search?offset=100",
      "start": "/api/action/datastore_search"
    },
    "fields": [...],
    "filters": {
      "childsageinweeks": 97
    },
    "records": [
      {
        "_id": 52,
        "charactercount": "118",
        "childsageinweeks": "97",
        "field_": "",
        "messageid": "1052",
        "messagetype": "Happy Birthday",
        "sequence": "1",
        "txt4totsmessage": "TXT4Tots: Happy 2nd Birthday! Congratulations on making it to the 2's in such a healthy way! Enjoy celebrating today. "
      }
    ],
    "resource_id": "abed461e-3eb0-4596-9e1e-3a45817e71c4",
    "total": 1
  },
  "success": true
}

Hospital Compare

The Hospital Compare dataset provides quality measures for hospitals. Use the Data API to search for hospitals by name or ZIP code. Here is how to execute such a query using the ‘curl’ command-line tool. The query parameters are passed in POST request in JSON format.

curl http://hub.Healthdata.gov/api/action/datastore_search --data-urlencode '
{
  "resource_id": "391792b5-9c0a-48a1-918f-2ee63caa1c54",
  "filters": {
    "addr_postalcode": 11803
  }
}'

The JSON result is:

{
  "help": ...,
  "result": {
    "_links": {
      "next": "/api/action/datastore_search?offset=100",
      "start": "/api/action/datastore_search"
    },
    "fields": [...],
    "filters": {
      "addr_postalcode": 11803
    },
    "records": [
      {
        "_id": 3211,
        "addr_city": "PLAINVIEW",
        "addr_line_1": "888 OLD COUNTRY ROAD",
        "addr_postalcode": "11803",
        "addr_state": "NY",
        "county_cd": "400",
        "emergency_serv_type": "Yes",
        "hospital_type": "Short-term",
        "hsp_accreditation": "",
        "hsp_name": "PLAINVIEW HOSPITAL",
        "ownership_type": "Voluntary non-profit - Private",
        "provider_id": "330331",
        "seqn": "3211",
        "tel_nbr": "5167193000"
      }
    ],
    "resource_id": "391792b5-9c0a-48a1-918f-2ee63caa1c54",
    "total": 1
  },
  "success": true
}

Finding The Data API Resource

To begin using the Data API, you must find the resource page on hub.Healthdata.gov, which is where the API is located.

Starting on the dataset listing page, such as TXT4Tots Message Library – English, scroll to the bottom of the page to find the "CKAN Page" link, which is an address on hub.Healthdata.gov. Follow that link. For TXT4Tots, the link takes you to this page. It is the dataset page on hub.Healthdata.gov.

Each dataset may have one or more resources listed under “Data and Resources." Each resource is a single table of data. Click the resource title to open the resource page. On the TXT4Tots Message Library – English dataset, there is a single CSV table resource. Click “CSV” to open this resource page.

The resource page shows a preview of the data table, including the list of field names that can be used in the API. At the top right of the page you will also see "Download" and "Data API" buttons. The Download button downloads the original raw data file for the resource (in this example, a CSV file). Click the Data API button for example URLs for querying the Data API for this resource.

Using the Data API

The Data API’s search method allows a developer to search the rows of the dataset. It can return:

  • All rows (paged with ‘limit’ and ‘offset’ parameters).
  • Rows matching a full-text search (using the ‘q’ parameter).
  • Rows matching particular field values (using ‘filters’).

A Data API query is a POST request to http://hub.Healthdata.gov/api/action/datastore_search. The query parameters are sent in a URL-encoded JSON dict. The parameters are:

  • resource_id: Required. The GUID of the resource to query. You can find the GUID in the URL for the resource page on hub.Healthdata.gov. For example, the GUID of the Hospital Compare’s Hospital Characteristics (HOSP) table is "391792b5-9c0a-48a1-918f-2ee63caa1c54."
  • limit: Optional. The maximum number of rows to return.
  • offset: Optional. The starting row number of the returned results (zero-based).
  • q: Optional. Text to use for a full-text search.
  • filters: Optional. A JSON dict of field-value pairs to filter the results on particular column values.

The response is a JSON dict with the following fields:

  • success: A boolean value indicating if the query was successful.
  • error: On failure, a dict containing error information.
  • result: On success, a dict containing the query results.

The result object has the following fields:

  • total: The total number of matching rows in the table.
  • records: An array of matching rows. Each row is a dict with name/value keys corresponding to the table’s columns.

See the CKAN documentation on datastore_search for further details and other search methods.

Python Examples

Example 1: Paging Results

The following Python example shows how to retreive the 21st through 30th rows of the Hospital Compare HOSP table:

import urllib, json

query = {
  "resource_id": "391792b5-9c0a-48a1-918f-2ee63caa1c54",
  "limit": 10,
  "offset": 20
}

results = urllib.urlopen(
  "http://hub.Healthdata.gov/api/action/datastore_search",
  urllib.quote(json.dumps(query)))

results = json.load(results)

for rec in results["result"]["records"]:
  print rec["hsp_name"]

Example 2: Full-Text Search

To make a full-text query, pass the query text in the ‘q’ parameter. Here is how to revise the query object from the previous example to perform a full-text query (the rest of the example is the same as above):

query = {
  "resource_id": "391792b5-9c0a-48a1-918f-2ee63caa1c54",
  "q": "Plainview"
}

Example 3: Filtering on Field Values

To filter by a particular field, specify the values of fields in a JSON dict and set it as the “filters” parameter. The field names are listed in the data table preview on the resource page on hub.Healthdata.gov, or in the response object of any query.

Here is how to revise the query object from the previous example to use filters instead of a full text search:

query = {
  "resource_id": "391792b5-9c0a-48a1-918f-2ee63caa1c54",
  "filters": {
    "addr_postalcode": 11803
  }
}