# US ENERGY STAR Unique ID (pd\_id) Portfolio Status Monitor (`plym-actor-factory/us-energy-star-pd-id-portfolio-monitor`) Actor

Watch ENERGY STAR Unique IDs (pd\_id) and emit typed APPEARED/DROPPED/MOST\_EFFICIENT events from the official EPA ENERGY STAR Model Index Socrata. Not Safer Choice twin; not TRI facility twin; not flat dump billed as rows; not unpaid energy SaaS.

- **URL**: https://apify.com/plym-actor-factory/us-energy-star-pd-id-portfolio-monitor.md
- **Developed by:** [Daniel Witney](https://apify.com/plym-actor-factory) (community)
- **Categories:** AI, Automation, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 energy star status event delivereds

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

## US ENERGY STAR Unique ID (pd\_id) Portfolio Status Event Monitor

Watch a book of **ENERGY STAR Unique IDs (`pd_id`)** and emit typed **APPEARED / DROPPED / MOST\_EFFICIENT\_GAINED / MOST\_EFFICIENT\_LOST** events when the official **EPA ENERGY STAR Model Index** Socrata snapshot changes for keys on that book.

**Not** an EPA Safer Choice twin (#37). **Not** a TRI facility twin (#31). **Not** a flat certified-products dump billed as rows. **Not** unpaid energy-SaaS scrape.

### Job (A1b wedge)

US utility rebate / retailer energy assortment / procurement / brand-compliance desks track a **customer-owned ENERGY STAR Unique ID book** and need Slack/JSON when a watched model **appears on / drops off the certified Model Index**, or **flips Most Efficient criteria** — without re-pulling the national table by hand.

A1b competitors cited from **phase3-a1b-next3-v14.md only**: **0** quiet ENERGY STAR pd\_id portfolio / Most-Efficient event PPE products. Database dump (different job): `nexgensignal/energy-star-product-records` (**1 MAU**, created 2026-08-22 — “one row per product” flat extract). Precision “ENERGY STAR product status / portfolio monitor” returns only that dump. Distinct from Safer Choice (#37) and TRI (#31).

### Source (official only)

| Path | URL | Notes |
|------|-----|-------|
| Portfolio live | `https://data.energystar.gov/resource/8wj2-sec8.json?$where=pd_id in(...)` | Official ENERGY STAR Model Index Socrata; live-verified 200; **SoQL `pd_id in(...)` batches** (portfolio-safe — never downloads the ~1.8M-row national table) |
| Program | https://www.energystar.gov/ | Attribution: ENERGY STAR / EPA |

No API key. Cite **ENERGY STAR** + retrieval date. Default product fields = pd\_id + partner + category + brand/model + UPC + Most Efficient flag (product/org data). CSV twin of the same resource is OK for offline research; this Actor uses JSON SoQL.

### Matching honesty

- **Primary key: `pd_id` (ENERGY STAR Unique ID)** — exact match after normalize (digits-only).
- Brand / model / UPC are **evidence fields** on events, not primary watch keys in this SKU.
- Covers published **currently certified** Model Index rows — drop events mean **removal from the published certified index**, not a full disqualification docket mailer.
- **Not** Safer Choice / DfE partnership status (different EPA program, ID scheme, and buyer desk).
- Cadence follows daily ENERGY STAR Socrata refresh — scheduled snapshot poll, not streaming.
- First observation of a watch key = **baseline only** (no product charge).
- Quiet / unchanged books ≈ **$0** product charge.
- National Model Index rows not on the book are **never** billed.

### Events (PPE)

| Event | When |
|-------|------|
| `ENERGY_STAR_APPEARED` | Watched pd\_id was missing, now present on Model Index |
| `ENERGY_STAR_DROPPED` | Watched pd\_id no longer returned for the watch key |
| `ENERGY_STAR_MOST_EFFICIENT_GAINED` | `meets_most_efficient_criteria` flips No → Yes |
| `ENERGY_STAR_MOST_EFFICIENT_LOST` | `meets_most_efficient_criteria` flips Yes → No |
| `RUN_STATUS` | Non-billable health row every successful run (`FIXTURE_HEALTH` / `MONITOR_IDLE` / …) |

Unknown/null Most Efficient transitions are **not** billed (honest — null ≠ a clear flip).

### Modes

- **`sourceMode=fixture`** (default): Store auto-test / CI. With `emitFixtureDemoEvents=false` (default) emits **only** `RUN_STATUS` / `FIXTURE_HEALTH` → **0** product charges.
- **`sourceMode=live`**: Official ENERGY STAR Model Index Socrata (**no API key**). SoQL `pd_id in(...)` batches — **not** a flat dump SKU.

### Pricing (Model A — ADR 0010)

- `energy-star-status-event-delivered` @ **$0.02** / unique delivered event ($20 / 1k)
- `apify-actor-start` @ **$0.00005**
- Quiet / baseline days ≈ **$0** product charge

### Legal

**GREEN** — EPA ENERGY STAR open data (data.energystar.gov); cite ENERGY STAR + retrieval date. Default product = pd\_id + partner + category + brand/model + UPC + Most Efficient (product/org data).

### Input

See `.actor/input_schema.json`. Primary field: `pdIds` (ENERGY STAR Unique IDs). Optional `signalGroups`: `presence`, `most_efficient`.

### Build order

Phase 3 **#39** (v14 A1b PASS #2 / GO #39). Pattern: US EPA Safer Choice / Illinois IDFPR licence portfolio status monitors.

# Actor input Schema

## `pdIds` (type: `array`):

Official ENERGY STAR Unique IDs (pd\_id) to monitor against the EPA ENERGY STAR Model Index Socrata (8wj2-sec8). Exact match after normalize (digits-only). Prefer pd\_id; brand+model+UPC are secondary evidence fields only. Invalid entries skipped with no charge.

## `signalGroups` (type: `array`):

Which change groups to evaluate: presence (APPEARED/DROPPED), most\_efficient (MOST\_EFFICIENT\_GAINED/LOST). Default: all.

## `maxRunSeconds` (type: `integer`):

Wall-clock budget for Socrata SoQL watchlist fetch + diff.

## `maxEvents` (type: `integer`):

Stop after this many unique change events are delivered (does not include RUN\_STATUS).

## `resumeFromCheckpoint` (type: `boolean`):

If true, resume pd\_id snapshots and seen event\_uids from the default Key-Value Store.

## `sourceMode` (type: `string`):

fixture = local/CI / Apify Store daily auto-test default (no network; emits RUN\_STATUS only unless emitFixtureDemoEvents=true). live = official ENERGY STAR Model Index Socrata (no API key; SoQL pd\_id in(...) batches — not a national dump).

## `emitFixtureDemoEvents` (type: `boolean`):

When sourceMode=fixture, if true push fabricated change events from local fixtures (unit/local demos only). Default false so Store daily auto-tests never emit fake ENERGY STAR events or charge energy-star-status-event-delivered. Production: leave false and use sourceMode=live. SAMPLE rows only: demo events use placeholder entities (never real companies/IDs), are flagged sample=true / isSample=true, and are NEVER charged.

## `asOfHint` (type: `string`):

Optional as\_of label for events / RUN\_STATUS. Defaults to Socrata X-SODA2-Truth-Last-Modified when present.

## `maxTotalChargeUsd` (type: `number`):

Optional soft budget hint for delivered change events. Platform ACTOR\_MAX\_TOTAL\_CHARGE\_USD also applies when set.

## `socrataUrl` (type: `string`):

Optional override for the official ENERGY STAR Model Index resource JSON URL. Default: https://data.energystar.gov/resource/8wj2-sec8.json

## `batchSize` (type: `integer`):

How many pd\_id values per Socrata $where=pd\_id in(...) request (default 40).

## Actor input object example

```json
{
  "pdIds": [
    "2182921",
    "2214627",
    "1723365"
  ],
  "signalGroups": [
    "presence",
    "most_efficient"
  ],
  "maxRunSeconds": 90,
  "maxEvents": 500,
  "resumeFromCheckpoint": true,
  "sourceMode": "fixture",
  "emitFixtureDemoEvents": false,
  "batchSize": 40
}
```

# Actor output Schema

## `OUTPUT` (type: `string`):

JSON summary: delivered, charged, runStatus, checkpoint, stats, ENERGY STAR coverage limits

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("plym-actor-factory/us-energy-star-pd-id-portfolio-monitor").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("plym-actor-factory/us-energy-star-pd-id-portfolio-monitor").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 '{}' |
apify call plym-actor-factory/us-energy-star-pd-id-portfolio-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,plym-actor-factory/us-energy-star-pd-id-portfolio-monitor"
        }
    }
}
```

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/6n7px3MjUUwh1Afh9/builds/YERNsOEw6t1KRGKAR/openapi.json