API Overview

Introduction

The Healthgraphic API allows you to retrieve data about conditions, medications, surgeries and much more. Our API is read-only and is organized around REST. The API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors.

We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application. JSON is returned by all API responses by default although XML can be requested.

To make the API as explorable as possible, accounts can obtain access tokens. Use the token to perform a live or test request.


Authentication

Authentication to the API is performed via access tokens attached to each request. To obtain an access token, you must authenticate using the GET TOKEN request.


 

Status codes

Healthgraphic uses conventional HTTP response codes to indicate the success or failure of an API request.

 

Status codeDescription
200Success. Everything worked as expected
400 The request was unacceptable, which due to missing a required parameter
403The parameters were valid but the request failed. Examples include expired token and token does not exist
404The requested resource doesn't exist
405Method not allowed
429Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
500Internal server error. Something went wrong on our end

Rate Limiting

The Healthgraphic API is rate limited to prevent abuse. Every API request is recorded and if more requests are made during a time period than allowed, requests will be rate limited until the end of the time period. The limits are high enough that typical use should rarely, if ever, be rate limited.

Requests that have been rate limited will respond with HTTP 429 Too Many Requests.

If your application is being negatively affected by rate limiting, please contact support@healthgraphic.com with details and we will help address the issue.


Versioning

When we make significant releases or backwards incompatible changes to the API, we release new versions. The current version is V1. 

To use a specific version of the API, you can set the parameter ‘version’ in the query header. If the header “version” is not sent, the latest version will be used by default.

To see the documentation for the version you are using, select the appropriate version from the menu in the left upper hand corner if applicable.


 

Pagination

Sometimes when you’re making calls to the Healthgraphic API, there will be a lot of results to return. For that reason, we allow you to paginate the results to make sure responses are easy to handle.

By default, pagination is disabled. But the results can be paginated by setting the parameters page and perPage in the call. If pagination is used, you can then make a call to return the next page when needed.


 

Resources

Token

You may authenticate requests to the API using the following request. You will receive a token that will allow you to access the API. A new token needs to be obtained every 30 minutes.

 

Get token

Retrieve an access token

Conditions

A condition is a state of health that may be normal or abnormal. An abnormal state or illness can further be classified as a disease. For example, pregnancy is a normal state of health and can be classified as a condition. Diabetes is an abnormal state of health and can be classified as a condition and disease.

 

This terminology is simplified by referring to any state of health as a condition.


What can you do with Conditions?

 

Get a condition

Retrieve details about a condition

 

Objects

NameDescriptionType
name
Name of the condition
string
label
Label attached to the condition
string
description
Description of the condition
string
synonyms
Other names for the condition
string
organ_system
Name, link and description of the key organ system(s) involved in the condition
string
body_part
Name, link and description of the key body part(s) involved in the condition
string

 

Get causes

Retrieve a list of causes of a condition

 

Objects

NameDescriptionType
name
Name of the causestring
label
Label attached to the cause
string
description
Description of the cause
string
synonyms
Other names for the cause
string

 

Get symptoms

Retrieve a list of symptoms of a condition

 

Objects

NameDescriptionType
name
Name of the symptomstring
label
Label attached to the symptom
string
description
Description of the symptom
string
synonyms
Other names for the symptom
string

 

Get diagnostic tests

Retrieve a summary and list of tests used to diagnose a condition

 

Objects

NameDescriptionType
summary
Summary of how the condition is diagnosed
string
name
Name of test string
label
Label attached to the test
string
description
Description of the test
string
link
MedlinePlus URL that explains frequently asked questions about the teststring
synonymsOther names for the teststring

 

Get treatments

Retrieve a summary and list of treatments for a condition

 

Objects

NameDescriptionType
summary
Summary of how the condition is treated
string
name
Name of treatmentstring
label
Label attached to the treatment
string
description
Description of the treatment
string
link
MedlinePlus URL that explains frequently asked questions about treatmentstring
synonymsOther names for the treatmentstring

 

Get risk factors

Retrieve a list of risk factors for a condition

 

Objects

NameDescriptionType
name
Name of risk factorstring
label
Label attached to the risk factor
string
description
Description of the risk factor
string
synonyms
Other names for the risk factor
string

 

Get complications

Retrieve a summary and list of complications of a condition

 

Objects

NameDescriptionType
summary
Summary of complication(s) of a condition
string
name
Name of complicationstring
label
Label attached to the complication
string
description
Description of the complicationstring
synonymsOther names for the complicationstring

 

Get consumer tools

Retrieve a list of relevant consumer tools for a condition

 

Objects

NameDescriptionType
name
Name of consumer toolstring
label
Label attached to the consumer tool
string
description
Description of the consumer tool
string

 

Get doctors

Retrieve a list of doctors that treat and/or diagnose the condition

 

Objects

NameDescriptionType
name
Name of doctorstring
label
Label attached to the doctor
string
description
Description of the doctorstring

 

Get mode of spread

Retrieve details about if and how the condition is spread

 

Objects

NameDescriptionType
name
Name of mode of transmissionstring
label
Label attached to the mode of transmission
string
description
Description of the mode of transmission
string
synonyms
Other names for the mode of transmission
string

 

 

Symptoms

A symptom is a subjective physical or mental feature indicative of a condition. A sign is an objective feature of a condition.

 

This terminology is simplified by referring to any feature of a condition as a symptom.


What can you do with Symptoms?

 

Get a symptom

Retrieve details about a symptom

 

Objects

NameDescriptionType
name
Name of symptomstring
label
Label attached to the symptom
string
description
Description of the symptom
string
synonyms
Other names for the symptom
string

 

Medications

A medication or drug is a substance used to diagnose, cure, treat or prevent a condition.


What can you do with Medications?

 

Get a medication

Retrieve details about a medication

 

Objects

NameDescriptionType
name
Name of medicationstring
label
Label attached to the medication
string
description
Description of the medication
string
medication_categoryName and description of category that medications belongs in string
medication_className and description of class that medication belongs instring
uses_linkMedlinePlus URL for uses of the medicationstring
side_effects_linkMedlinePlus URL for medication side effectsstring
warnings_linkMedlinePlus URL for medication warningsstring
reviewsExternal URL for patient reviews of medicationstring
synonyms
Other names for the medication
string

 

Medical Tests

A medical test is a procedure or exam used to detect, diagnose or monitor a condition or disease.


What can you do with Medical Tests?

 

Get a test

Retrieve details about a medical test

 

Objects

NameDescriptionType
name
Name of medical teststring
label
Label attached to the medical test
string
description
Description of the medical teststring
linkMedlinePlus URL that explains frequently asked questions about the teststring
synonyms
Other names for the medical test
string

Surgeries

A surgery is an operative procedure that involves cutting open the human body to investigate or treat a condition or disease.


What can you do with Surgeries?

 

Get a surgery

Retrieve details about a surgery

 

Objects

NameDescriptionType
name
Name of surgerystring
label
Label attached to the surgerystring
description
Description of the surgery
string
linkMedlinePlus URL that explains frequently asked questions about the surgerystring
synonymsOther names for the surgerystring

 

Consumer tools

A consumer tool is a web-based resource or support tool that helps healthcare consumers make more informed decisions.


What can you do with Consumer Tools?

 

Get medication pricing

Retrieve a list of public facing websites for finding and comparing medication prices

 

Objects

NameDescriptionType
name
Name of medication pricing toolstring
label
Label attached to medication pricing tool
string
linkURL for medication pricing toolstring

 

Get hospital ratings

Retrieve a list of public facing websites for finding hospital ratings

 

Objects

NameDescriptionType
name
Name of hospital rating toolstring
label
Label attached to hospital rating toolstring
linkURL for hospital rating toolstring

 

Get doctor appointment scheduling

Retrieve a list of public facing websites for scheduling a doctor’s appointment

 

Objects

NameDescriptionType
name
Name of doctor appointment scheduling toolstring
label
Label attached to doctor appointment scheduling toolstring
linkURL for doctor appointment scheduling toolstring

 

Get healthcare prices

Retrieve a list of URLs of tools for finding the prices of medical services

 

Objects

NameDescriptionType
name
Name of healthcare pricing toolstring
label
Label attached to healthcare pricing toolstring
linkURL for healthcare pricing toolstring

 

Searching

Global and resource-specific search can be performed to retrieve resources.


What can you do with Search?

 

Search for condition

Search for condition

 

Objects

NameDescriptionType
name
Name of conditionstring
label
Label attached to the condition
string
description
Description of the conditionstring

 

Search for medication

Search for medication

 

Objects

NameDescriptionType
name
Name of medicationstring
label
Label attached the medication
string
description
Description of the medicationstring

 

Search for surgery

Search for surgery

 

Objects

NameDescriptionType
name
Name of surgerystring
label
Label attached the surgery
string
description
Description of the surgerystring

 

Search for test

Search for test

 

Objects

NameDescriptionType
name
Name of teststring
label
Label attached the test
string
description
Description of the teststring

 

Search for symptom

Search for a symptom

 

Objects

NameDescriptionType
name
Name of symptomstring
label
Label attached the symptom
string
description
Description of the symptomstring

 

Search for entity

Search for entity

 

Objects

NameDescriptionType
name
Name of entitystring
label
Label attached the entity
string
description
Description of the entitystring

 

Search for entity by synonym

Search for entity by synonym

 

Objects

NameDescriptionType
name
Name of entitystring
label
Label attached the entity
string
description
Description of the entitystring
synonymsOther names for the entitystring

No method selected

You can try selecting a method from left column