Accessing Trilliant Health’s Demand Forecast

image by Midjourney — a happy line drawing of a doctor using a compass and ruler to plot a line chart on a big piece of paper

Trilliant Health recently announced that its national demand forecast, which makes highly specific 10-year projections of healthcare demand across multiple care disciplines, will be available to the public at no cost.

Forecasts are built on their all-payer database of claims from over 300 million Americans and provide hyper-local probabilistic modeling of projected volume segmented by patient demographics and procedure categories.

This article is a step-by-step walkthrough of how to sign up for and return data from the Demand Forecast National Basic API. You can read more about Trilliant Health’s Demand forecast on their website and then follow the link to sign up, or jump straight into the developer portal linked below!

Signing Up

Visit the developer portal at https://portal.api.trillianthealth.com/login and click Sign Up. After entering your email and name information, you’ll get a confirmation email that will prompt you to complete creating your account and take you to the main landing page.

Create an Application

Once you’re in the portal, you’ll need to create a new application to get credentials that will allow you to call the endpoints. Click Demand Forecast National Basic to enter the main product screen, then click Register for V1 and follow the prompts to Create an Application.

Apply Credentials

After creating an application, you’ll be prompted to request access. This is where you generate a key. After creating your first Application, you’ll receive a Request Access prompt. Clicking it brings you to the app management screen, where you’ll click +Generate Credentials. Give your credential a name, then click Confirm & Copy.

After clicking Confirm & Copy, the key will be on your clipboard. Keep it in a safe place, as you won’t have access to it again, and you’ll need it to test the API.

Authorization in the Portal

You’ll need to enter your key in the portal if you want to make a test call. From the app management screen, click Catalog next to your email address to get back to the portal landing page, then click Demand Forecast National Basic. Click Authorize and enter the key you generated in the last step, then click Close. You’re now ready to make a test call!

Finding Parameters to Query

The /demand-forecast-criteria-options endpoints return all parameter field names and all available enumerations so you can filter your forecasts to a specific demographic. The two criteria-options endpoints are common, which provide parameters and enums that are shared between all care disciplines, and a care discipline-specific endpoint, which provides parameters and enums that are specific to your care discipline.

Calling the Common Options Endpoint

Three parameter fields are common to all care disciplines and will allow you to filter the patient demographics. They are:

• ageGroup: the age range of patients at the time of their visit.
• gender: the gender a patient has listed on their healthcare claim.
• careSetting: where the visit took place, either an inpatient or outpatient setting.

To get a list of enumerations for these parameters, start on the Demand Forecast National Basic page. The Common endpoint is in its own group at the top of the GET options. Click GET /v1/demand-forecast-criteria-options/common, then Try it out and finally Execute.

The response will look something like this. When we pull our actual forecast later on, we will return the forecast specific to where gender=MALE.

{
  "ageGroups": [
    "0-14",
    "15-34",
    "35-49",
    "50-64",
    "65-84",
    "85+"
  ],
  "genders": [
    "MALE",
    "FEMALE"
  ],
  "careSettings": [
    "INPATIENT",
    "OUTPATIENT"
  ]
}

Calling Care Discipline-Specific Options Endpoint

Procedure categories are unique to each care discipline and can be found in each care discipline grouping. For example, here’s the Surgical criteria options endpoint:

To return a list of field names and enums, click Get /v1/demand-forecast-criteria-options/surgical, then Try it out, and finally Execute. As with the common options, this endpoint doesn’t support search parameters; it just returns surgical-specific parameters.

The response will look something like the JSON below. The Surgical procedure groupings consist of serviceLine, which is the highest, most general grouping of procedures, and procedureSubType, which is a more detailed aggregation.

When we pull a forecast later on, we’lll use the serviceLine.name of Heart/Vascular.

{
  "serviceLines": [
    {
      "name": "Endocrine System",
      "procedureSubTypes": [
        "Adrenal and Pituitary Procedures",
        "Other Endocrine Nutritional and Metabolic O.R. Procedures",
        "Thyroid Parathyroid and Thyroglossal Procedures"
      ]
    },
    {
      "name": "ENT",
      "procedureSubTypes": [
        "Mouth Procedures",
        "Other Ear Nose Mouth and Throat O.R. Procedures",
        "Salivary Gland Procedures",
        "Sinus and Mastoid Procedures"
      ]
    },
    {
      "name": "Heart/Vascular",
      "procedureSubTypes": [
        "Arterial Procedures",
        "Cardiac Assist Procedures",
        "Cardiac Catheterization",
        "Cardiac Electrophysiology",
        ...
       ]
    },
    ...

Note that in the National Basic version of Demand Forecast, forecasts are only provided at the serviceLine level, which in the JSON example above, are “Endocrine System”, “ENT”, and “Heart/Vascular”. If you’re interested in more detailed forecasts at the procedureSubTypes level, you can contact Trilliant Health for more information.

Returning a Specific Forecast

We now have two parameters we want to use to get a specific forecast for:

• gender = MALE
• serviceLine = Heart/Vascular

To return a forecast, click GET /v1/demand-forecast/surgical/nationwide on the main product page. You’ll be presented with parameter options.

Click Try it out and then enter the gender and serviceLine parameters we found above.

That leaves ageGroup, careSetting, and procedureSubType blank. When a parameter is left blank, the forecast returned is not filtered by those values. In our example, not specifying these parameters means we return a forecast with:

• ageGroup: patients of any age.
• careSetting: visits that take place in either an inpatient or outpatient setting.
• procedureSubType: Heart/Vascular procedures of any procedureSubType.

Once your parameters are filled, click Execute, and your results will appear below!

The response JSON will look like this.

{
  "segment": {
    "geo": {
      "type": "nationwide"
    },
    "ageGroup": null,
    "gender": null,
    "careSetting": null,
    "serviceLine": "Heart/Vascular",
    "procedureSubType": null
  },
  "projections": {
    "2016": {
      "population": 323580626,
      "incidentRates": {
        "mean": 207.87587592824698,
        "percentile10": 189.38257876585604,
        "percentile25": 197.6137190495516,
        "percentile50": 206.63437823337472,
        "percentile75": 217.0951054464594,
        "percentile90": 227.68819391953073,
        "observed": 195
      },
      "counts": {
        "mean": 6726460.60631605,
        "percentile10": 6128053,
        "percentile25": 6394397,
        "percentile50": 6686288,
        "percentile75": 7024777,
        "percentile90": 7367548
      }
    },
    ...

Interpreting the Response

The JSON response contains two main objects.

The segment object shows what filters you have on the data. In our example, we’re calling the Surgical endpoint and passed parameter values of MALE for gender and Heart/Vascular for serviceLine. Therefore, our forecast is for all males receiving Heart/Vascular procedures in the United States.

The projectionsobject contains a yearobject for each year in the forecast, and within each year is a distribution of possible outcomes for your unique forecast. A distribution of possible values for incidentRate(per population of 10,000) and count appear within each year. These are what you can use to project future outcomes. Providing a distribution, rather than a single number, means you can provide a range of possible outcomes for each year. Plotting the 25th, 50th, and 75th percentile values for each year is a more honest way to represent possible values rather than trying to pick a single value, which is almost certainly going to be wrong.

Graphing the Data

Using the API in concert with a graphing tool like Plotly in Python, you can develop plot data to make more easily interpreted versions of forecasts.

For a step-by-step tutorial on creating these charts, see this article.

Adding More Detail

Projections at a national level by patient demographic are useful as a generalization, but healthcare trends are a highly local phenomenon. Using a nationally forecasted incident rate to predict visits at a local level can be misleading. Coronary Bypass operations within the Surgical Heart/Vascular service line will have very different forecasts in Oregon and Mississippi.

The subscription-based versions of Demand Forecast provide a more detailed breakdown of geography, with forecasts calculated at the state, Core-Based Statistical Area (CBSA), and ZIP code level. Additionally, the next level of procedure subcategorizations is available for each service line. These were the procedureSubType values for Surgical in the Calling Care Discipline-Specific Options Endpoint section above.

If you’re interested in finding out more about the expanded Demand Forecast products, you can contact Trilliant Health for more information.