# Winter Heating Fuel Budget Planner by State and ZIP (`standardwork/winter-heating-budget-planner`) Actor

Month-by-month winter heating cost for propane, heating oil, natural gas, or electricity from your state's latest public prices and local degree days.

- **URL**: https://apify.com/standardwork/winter-heating-budget-planner.md
- **Developed by:** [Standard Work Co.](https://apify.com/standardwork) (community)
- **Categories:** Real estate, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$20.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Winter Heating Fuel Budget Planner by State and ZIP

**Informational only. Not for navigation, safety, emergency, financial, medical, or legal decisions. Check the official source before you rely on it.**

Estimates, not a quote or a bill. Your supplier's price, your home, and this winter's weather will differ.

### What it does

Enter your state, your heating fuel, and either your home size or last winter's usage. You get a month-by-month budget for October through April with:

- your area's average heating degree days (last 10 complete winters by default, statewide or at your ZIP code),
- the latest public residential price for your fuel in your state,
- estimated fuel use, estimated cost, and a running total,
- one season total row.

Fuels: propane, heating oil, natural gas, electricity (resistance or heat pump), plus kerosene, wood pellets, and cord wood with your own price.

### How to use it (no code)

1. Click **Try for free** or **Start**.
2. Type your two-letter state code, for example `OH`. Add your ZIP code if you want weather for your exact area.
3. Pick your fuel type.
4. Enter your heated square feet and pick poor, average, or good insulation. Or, if you know how much fuel you used last winter, enter it in **Past winter usage**. That is more accurate.
5. Optional: enter your own price per gallon, Mcf, kWh, ton, or cord.
6. Click **Start**. Results appear in the table in under a minute. Export to Excel, CSV, or JSON.

### Example input

```json
{"state": "OH", "fuelType": "propane", "homeSqft": 1800, "insulation": "average"}
```

### Output fields

Each row has the same fields in the same order. Missing values are null.

| Field | Meaning |
|---|---|
| rowType | `month`, `season total`, or `error` |
| monthName, month | Month of the coming winter |
| estimatedCost, cumulativeCost | Estimated dollars for the month and running total |
| usageUnits, unit | Estimated fuel use (gallons, Mcf, kWh, tons, or cords) |
| pricePerUnit, priceLevel, priceAsOf, priceSeries | Price used, whether it is your state, your region, the U.S. average, or your input, and its date |
| normalHdd, hddYears, weatherArea | Average heating degree days (base 65 F) and the years and area they cover |
| method, assumptions, note | How usage was estimated and any limits |
| sourceUrl, hddSourceUrl, credit | Where the numbers came from |
| retrievedAt, retrievedAtLocal | When the data was pulled (ISO 8601 with offset, and U.S. Central time) |
| qcStatus, qcNotes, error | Self-check result (`ok` or `flagged`) and any error |

### How the estimate works

- **Home size method:** square feet x a heat loss factor (poor 10, average 7, good 4.5 BTU per square foot per degree day) x degree days, divided by the fuel's energy content and your system efficiency. The factors are typical values, not a measurement of your home.
- **Past usage method:** your winter total is spread across October to April in proportion to degree days.
- Energy content used: propane 91,452 BTU per gallon, heating oil 138,500, kerosene 135,000, natural gas 1,036,000 per Mcf, electricity 3,412 per kWh, wood pellets 16.5 million per ton, cord wood 20 million per cord.
- Default efficiency: propane and gas 90%, oil and kerosene 83%, pellets 80%, cord wood 65%, electric resistance 100%. Use about 250% for a heat pump.

### Limits

- Propane and heating oil prices come from a weekly government survey that runs about October to March and covers some states. States without their own price get their region's average, or the U.S. average. The row says which.
- The latest weekly price is used for every month. Winter prices often rise.
- Natural gas uses the most recent published price for the same calendar month (last season). Some states withhold some months.
- Electricity uses the latest monthly statewide average, which lags about 3 months.
- No free public state price exists for kerosene, wood pellets, or cord wood, so you must enter your own.
- Statewide weather is an area average, not weighted by where people live. Use a ZIP code for your area.
- Hot water, cooking, and dryer use are not included.

### Disclaimer

Informational only. Not for navigation, safety, emergency, financial, medical, or legal decisions. Check the official source before you rely on it.

This is an independent tool by Standard Work Co. It is not affiliated with, endorsed by, or sponsored by any government agency named here. Agency names are used only to say where the data comes from.
The data comes from public government sources and is passed through as published, only reformatted. Government data can be preliminary, late, missing, revised, or wrong, and this tool can fail too. This output is not an official government record.
Provided "as is" with no warranty of any kind, including accuracy, completeness, or timeliness. You are responsible for checking the official source before acting on anything here. Liability is limited as stated in the Apify Standard Actor Contract for this tool.

Heating budget: these are estimates, not a price quote, a bill, or financial advice. Call your fuel supplier or utility for a current price. Have heating equipment serviced by a qualified technician.

### Data sources and credits

- Fuel prices: U.S. Energy Information Administration, public domain. Weekly heating oil and propane residential prices (State Heating Oil and Propane Program), monthly residential natural gas prices, and Electric Power Monthly Table 5.6.A. Source: U.S. Energy Information Administration (date shown in each row).
- Heating degree days: Applied Climate Information System (RCC-ACIS) gridded daily data, NRCC interpolated grid.
- ZIP code points: U.S. Census Bureau 2024 Gazetteer ZIP Code Tabulation Areas, public domain.

# Actor input Schema

## `state` (type: `string`):

Two-letter U.S. state code, for example OH. Fuel prices come from this state (or its region when the state has no published price).

## `zip` (type: `string`):

Optional 5-digit ZIP. When set, weather (heating degree days) comes from the grid point at the ZIP's center instead of the statewide average. Prices still come from the state above.

## `fuelType` (type: `string`):

Your main heating fuel. Kerosene, wood pellets, and cord wood have no free public state price, so enter your own price for those.

## `homeSqft` (type: `integer`):

Heated square feet. Used when past usage is not given. 200 to 20000.

## `insulation` (type: `string`):

Rough home tightness. Poor (older, drafty), average, or good (newer or upgraded). Used only with floor area.

## `annualUsage` (type: `number`):

If you know how much fuel you used last winter (gallons, Mcf, kWh, tons, or cords to match the fuel), enter it. This replaces the floor area estimate and is spread across months by degree days.

## `efficiencyPercent` (type: `number`):

Leave blank for typical values (propane and gas 90, oil and kerosene 83, pellets 80, cord wood 65, electric resistance 100). Use about 250 for an electric heat pump.

## `pricePerUnit` (type: `number`):

Your own price in dollars per gallon, Mcf, kWh, ton, or cord. Overrides the public price. Required for kerosene, wood pellets, and cord wood.

## `winters` (type: `integer`):

How many recent complete winters to average for heating degree days. 3 to 30.

## Actor input object example

```json
{
  "state": "OH",
  "fuelType": "propane",
  "homeSqft": 1800,
  "insulation": "average",
  "winters": 10
}
```

# Actor output Schema

## `results` (type: `string`):

All rows in the default dataset.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "state": "OH"
};

// Run the Actor and wait for it to finish
const run = await client.actor("standardwork/winter-heating-budget-planner").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "state": "OH" }

# Run the Actor and wait for it to finish
run = client.actor("standardwork/winter-heating-budget-planner").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "state": "OH"
}' |
apify call standardwork/winter-heating-budget-planner --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,standardwork/winter-heating-budget-planner"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/DIvv69B7rT4IeujdZ/builds/QgNkUUyCaCRbp7nae/openapi.json