ICD-9 API Documentation

{beta}


Cheat sheet


Endpoints

Specific ICD-9 code

Call

Use the URL format api.aqua.io/codes/beta/icd9/CODE_NAME.json via an HTTP GET request.

Code name should be formatted so that the decimal ('.') is replaced with a dash ('-'). e.g., V01.5 should be formatted as V01-5.

Response

Field
Explanation
Example Value
name
The ICD-9 code.
042
description
The condition the code describes.
Human immunodeficiency virus [HIV] disease
explanation
Additional explanation of how to properly use or understand the code, if any.
Acquired immune deficiency syndrome...
wikipedia_url
Relevant Wikipedia link, if available.
http://en.wikipedia.org/wiki/ Human_immunodeficiency_virus
valid_years
An array of years for which this code is valid (i.e., was included in the CMS ICD-9-CM file for that year). (More about valid code years.)
["1997", "1998", "2000", "2001", "2002", "2003", "2004", "2005", "2006", "2007", "2008", "2009", "2010", "2011"]
ancestors
An array of "ancestor" or ascendant codes and code categories, the highest level code/category provided first. If the code is already top-level, returns an empty array.
[{"ancestor": {"name": "001-139", "description": "INFECTIOUS AND PARASITIC DISEASES (001-139)", "explanation": "Note:\tCategories for \"late effects\" of infectious and parasitic diseases are to be found at 137-139.\r\nIncludes:\tdiseases generally recognized as communicable or transmissible as well as a few diseases of unknown but possibly infectious origin\r\nExcludes:\tacute respiratory infections (460-466)\r\ncarrier or suspected carrier of infectious organism (V02.0-V02.9)\r\ncertain localized infections\r\ninfluenza (487.0-487.8, 488.01-488.19)", "url":"https://aqua.io/codes/ icd9/2011/001-139"}}, {"ancestor": {"name": "042-042", "description": "HUMAN IMMUNODEFICIENCY VIRUS (HIV) INFECTION (042)", "explanation":"", "url":"https://aqua.io/codes/ icd9/2011/042-042"}}]
children
An array of "children" or descendant codes. If the code is bottom-level, returns an empty array.
[ ]
equivalents
An array of ICD-10 code equivalents, including equivalancy flag and translation. (More about code equivalents.)
[{"equivalent":{"name":"B20","description":"Human immunodeficiency virus [HIV] disease","explanation":"INCLUDES: acquired immune deficiency syndrome [AIDS]...","flag":"00000", "equivalency_strength":"completely equivalent meaning (identical match)","url": "https://api.aqua.io/codes/icd10/2013/b20.json"}}]
hcc_group_2014
HCC grouping for 2014 (may be 'null').
{name: "1", description: "HIV/AIDS"}
hcc_group_2013
HCC grouping for 2013 (may be 'null').
{name: "1", description: "HIV/AIDS"}
rxhcc_group_2014
RxHCC grouping for 2014 (may be 'null').
{name: "1", description: "HIV/AIDS"}
pace_esrd_group_2014
PACE/ESRD grouping for 2014 (may be 'null').
{name: "1", description: "HIV/AIDS"}
Full output for ICD-9 code 042

Good to know

  • The call URL may specify a code modification year, e.g. api.aqua.io/codes/beta/icd9/2011/250-1.json Only modifications maintained by the CDC and published online are available. Not specifying a year returns the codes from all available years.

  • Calls that do not specify an API version will default to the most current API, e.g. api.aqua.io/codes/icd9/250-1.json .

    Since future API versions may break implementations using prior versions, however, we strongly recommend specifying a version.
  • A malformed code request will return a 404 Status Error and, in many cases, an array of possible matches. For example api.aqua.io/codes/beta/icd9/25001.json returns

    {"possible_matches":[{"name":"250.1","description":"Diabetes with ketoacidosis","explanation":"[0-3]\r\nDiabetic:\r\nacidosis without mention of coma\r\nketosis without mention of coma","url":"https://api.aqua.io/codes/icd9/2011/250-1.json"},...}

    This can be useful for returning a 'did you mean...?' list of options to a user, if an inputted code contains a typo.

All top-level codes

Call

Use the URL format api.aqua.io/codes/beta/icd9.json via an HTTP GET request.

Response

Returns a JSON array of all top-level ICD-9 codes, each containing the following fields:

Field
Explanation
Example Value
name
The ICD-9 code.
001
description
The condition the code describes.
Cholera
url
API URL for the code.
https://api.aqua.io/codes/icd9/2011/001.json
Output for all ICD-9 codes.

Good to know

  • As with individual codes, call URL may specify a code modification year, e.g. api.aqua.io/codes/beta/icd9/2011.json

  • Calls that do not specify an API version will default to the most current API, e.g. api.aqua.io/codes/icd9.json .

    Since future API versions may break implementations using prior versioms, however, we strongly recommend specifying a version.

Search

Call

Use the URL format GET .../icd9.json?utf8=✓&q%5BSEARCH_PARAMETERS%5D=QUERY via an HTTP GET request.

Response

Returns a JSON array of matching results, each containing the following fields:

Field
Explanation
Example Value
name
The ICD-9 code.
066.4
description
The condition the code describes.
West Nile fever
url
API URL for the code.
https://api.aqua.io/codes/icd9/2011/066-4.json

Query Parameters

A search may query a code 'name', 'description', or a both fields ('name_or_description'). Each field may be queried using any of the following suffixes:

Suffix
Explanation
Example Implementation
X_cont=Y
Field X contains Y
...%5Bdescription_cont%5D=west_nile...
X_start=Y
Field X starts with Y
...%5Bname_start%5D=V...
X_end=Y
Field X ends with Y
...%5Bname_end%5D=.01...

FAQs

What are the benefits of using ICD codes in developing an app?

ICD codes are the internationally-recognized standard for classifying medical diagnoses. They feature prominently in EHRs and other clinical systems that gather health data, as well as in most standards for transmitting healthcare data, like HL7.

Using ICD codes instead of "free form" descriptions of diseases in an app helps ensure interoperability with systems that collect healthcare data. This can mean not only making consumer-generated data more relevant to the clinical environment, but also providing a key for consumers to interpret clinical data in plain language.

What are ICD-10 equivalents? How are they determined?

Most medical coding and billing in the U.S. is currently transitioning from using ICD-9 to ICD-10. The equivalents provide a roadmap for converting the codes from one standard to the other, as well as for providing a helpful forward reference to those not familiar with the ICD-10 code system.

All equivalents in the API are mapped according to the ICD-10 General Equivalance Mappings (GEM) provided by the Centers for Medicare & Medicaid Services (CMS).

Why do equivalents have 'flag' and 'equivalency_strength' fields?

Not all the equivalents provided in the CMS GEM are identical matches--some codes have multiple possible matches, since the target code system may be more or less specific than the source code system.

A flag is a five digit code in the CMS GEM meant to provide a guide in properly mapping a code from one system to the other. An explanation of the flags can be found here.

An equivalency_strength field is a semantic interpretation of the CMS GEM flags, for those who do not have the time to closely familiarize themselves with the flag system, or build logic to convert the flags to a semantic system.The equivalencey_strengths are provided as a courtesy, and should not be considered as superceding or replacing the flag system.

Are the equivalents bi-directional?

No, CMS provides two different lists for ICD-9-to-10 and ICD-10-to-9 conversion. Sometimes, there is no single proper equivalency, and multiple options are provided. The equivalents given for each API reflect this.

Which ICD-9 codeset years are included?

All the years available from CMS: 1997, 1998, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, and 2013

NOTE: 2013 is the last ICD-9-CM specification published by CMS, even though ICD-9 will continue to remain in service until October 2015. As a result, 2014 and 2015 are included as "valid years" in the ICD-9 API. Results returned for searches of 2014 or 2015 codes are from the 2013 specification.

Why do I get the error 'Invalid year passed as parameter' when I try to retrieve codes for 1999?

Currently, CMS does not have the 1999 codeset available for public access, so the 1999 codeset is not available via the API.

If the 1999 codeset is not offered, why is '1999' returned in the valid_years array?

Where it is almost certain that a code was supported in 1999 (the code was supported in both 1998 and 2000), the year is added to the valid_years field. Where it is possible the code was supported in 1999 (such as the code is supported in 2000, but not 1998) the year is added with an asterisk (e.g., '1999*').



Coding APIs

Code Search