Hospital Inpatient Prevention Quality Indicators for Adult Discharges by County (SPARCS) API : Beginning 2009

This featured Application Programming Interface (API) page serves as a reference for developers who are building tools that interact with the data on Health Data NY. The page provides examples on how to retrieve data from each of the fields within the dataset. A description of each field is also provided. This specific API page is for the Hospital Inpatient Prevention Qualtiy Indicators (PQI) for Adult Discharges by County (SPARCS): Beginning 2009 dataset. This is one of two datasets that contain observed and expected rates for Agency for Healthcare Research and Quality Prevention Quality Indicators – Adult (AHRQ PQI) beginning in 2009. The Agency for Healthcare Research and Quality (AHRQ) Prevention Quality Indicators (PQIs) are a set of population based measures that can be used with hospital inpatient discharge data to identify ambulatory care sensitive conditions. These are conditions where 1) the need for hospitalization is potentially preventable with appropriate outpatient care, or 2) conditions that could be less severe if treated early and appropriately. All PQIs apply only to adult populations (over the age of 18 years). The rates were calculated using Statewide Planning and Research Cooperative System (SPARCS) inpatient data and Claritas population information. The observed rates and expected rates for each AHRQ PQI is presented by either resident county (including a statewide total) or resident zip code (including a statewide total). This dataset is available at:https://health.data.ny.gov/Health/Hospital-Inpatient-Prevention-Quality-Indicators-f/iqp6-vdi4. For more information about the dataset, go to the dataset and look in the "About" section.

Getting Started

All communication with the API is done through HTTPS, and errors are communicated through HTTP response codes. Available response types include JSON, XML, and CSV, which are selectable by the "extension" on API requests or by HTTP Accepts headers.

This documentation also includes inline, runable examples. Click on any link that contains a gear symbol next to it to run that example live against the Hospital Inpatient Prevention Quality Indicators for Adult Discharges by County (SPARCS) API : Beginning 2009 API.

App Tokens

All requests should include an app token that identifies your application, and each application should have its own unique app token. A limited number of requests can be made without an app token, but they are subject to much lower throttling limits than request that do include one. If you don't have an app token yet, click the button to the right to sign up for one.

Once you have an app token, you can include it with your request either by using the X-App-Token HTTP header, or by passing it via the $app_token parameter on your URL.

Response Codes

One of the following response codes will be returned with every request:

  1. 200Successful request.
  2. 202Request processing. You can retry your request, and when it's complete, you'll get a 200 instead.
  3. 400Bad request
  4. 401Unauthorized. You're not authorized to access this resource.
  5. 404Not found. The resource requested doesn't exist.
  6. 429Too Many Requests. The client has made too many requests and is currently being rate limited.
  7. 500Server errors. Our bad!

Code Samples

#!/usr/bin/env ruby

require 'net/https'
uri = URI('https://health.data.ny.gov/resource/hospital-inpatient-prevention-quality-indicators-for-adult-discharges-by-county-sparcs-beginning-2009.json?recall_id=94')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_PEER

request = Net::HTTP::Get.new(uri.request_uri)
request.add_field('X-App-Token', ARGV[0])

response = http.request(request)
puts response.code
puts response.body
#!/usr/bin/env python

import sys
import requests

r = requests.get('https://health.data.ny.gov/resource/hospital-inpatient-prevention-quality-indicators-for-adult-discharges-by-county-sparcs-beginning-2009.json?recall_id=94', headers={'X-App-Token': sys.argv[1]})
print r.status_code
print r.text
request = require 'request'
options = uri: 'https://health.data.ny.gov/resource/hospital-inpatient-prevention-quality-indicators-for-adult-discharges-by-county-sparcs-beginning-2009.json?$$app_token=APP_TOKEN&recall_id=94'
request options, (err, response, body) ->  console.log body
#!/bin/sh 

curl --header "X-App-Token: $1" "https://health.data.ny.gov/resource/hospital-inpatient-prevention-quality-indicators-for-adult-discharges-by-county-sparcs-beginning-2009.json?recall_id=94"

Fields

The following fields are available on the Hospital Inpatient Prevention Quality Indicators for Adult Discharges by County (SPARCS) API : Beginning 2009 API.

year

Human Name: Year
Type: number
The year of both the hospital PQI discharge and the county population used in calculation of rates.

Examples

Retrieve all records with year equal to 2012:

Retrieve all records where year is within 1 kilometer of Seattle, WA (47.598177,-122.33448):

https://health.data.ny.gov/resource/hospital-inpatient-prevention-quality-indicators-for-adult-discharges-by-county-sparcs-beginning-2009.json?$where=within_circle(year, 47.598177,-122.33448, 1000)

patient_county

Human Name: Patient County
Type: text
The patient’s county of residence at time of discharge. Due to small population size, Hamilton and Schuyler counties are combined. Hospital discharges that did not have an accurate New York State county were excluded from the county analysis dataset.

Examples

Retrieve all records with patient_county equal to YATES:

Retrieve all records where patient_county is within 1 kilometer of Seattle, WA (47.598177,-122.33448):

https://health.data.ny.gov/resource/hospital-inpatient-prevention-quality-indicators-for-adult-discharges-by-county-sparcs-beginning-2009.json?$where=within_circle(patient_county, 47.598177,-122.33448, 1000)

pqi_number

Human Name: PQI Number
Type: text
The value code assigned to the PQI measure.

Examples

Retrieve all records with pqi_number equal to PQI_S03:

Retrieve all records where pqi_number is within 1 kilometer of Seattle, WA (47.598177,-122.33448):

https://health.data.ny.gov/resource/hospital-inpatient-prevention-quality-indicators-for-adult-discharges-by-county-sparcs-beginning-2009.json?$where=within_circle(pqi_number, 47.598177,-122.33448, 1000)

pqi_name

Human Name: PQI Name
Type: text
The descriptive name of the PQI measure.

Examples

Retrieve all records with pqi_name equal to Urinary Tract Infection:

Retrieve all records where pqi_name is within 1 kilometer of Seattle, WA (47.598177,-122.33448):

https://health.data.ny.gov/resource/hospital-inpatient-prevention-quality-indicators-for-adult-discharges-by-county-sparcs-beginning-2009.json?$where=within_circle(pqi_name, 47.598177,-122.33448, 1000)

observed_rate_per_100_000_people

Human Name: Observed Rate Per 100,000 People
Type: number
The number of PQI discharges in the county divided by the county population, multiplied by 100,000.

Examples

Retrieve all records with observed_rate_per_100_000_people equal to 2981.99:

Retrieve all records where observed_rate_per_100_000_people is within 1 kilometer of Seattle, WA (47.598177,-122.33448):

https://health.data.ny.gov/resource/hospital-inpatient-prevention-quality-indicators-for-adult-discharges-by-county-sparcs-beginning-2009.json?$where=within_circle(observed_rate_per_100_000_people, 47.598177,-122.33448, 1000)

expected_rate_per_100_000_people

Human Name: Expected Rate Per 100,000 People
Type: number
The expected number of PQI discharges in the county, adjusted by age, gender and race/ethnicity divided by the county population, multiplied by 100,000.

Examples

Retrieve all records with expected_rate_per_100_000_people equal to 2047.65:

Retrieve all records where expected_rate_per_100_000_people is within 1 kilometer of Seattle, WA (47.598177,-122.33448):

https://health.data.ny.gov/resource/hospital-inpatient-prevention-quality-indicators-for-adult-discharges-by-county-sparcs-beginning-2009.json?$where=within_circle(expected_rate_per_100_000_people, 47.598177,-122.33448, 1000)