# Texas Electricity Plans Scraper (`silentshadow55/electricity-plans-actor`) Actor Get every retail electricity plan for any Texas ZIP code from Power to Choose — plus what no one else offers: each plan's Electricity Facts Label PDF parsed into structured rates (energy charge, base charge, TDU fees, bill credits, ETF) and true monthly cost at your usage level. - **URL**: https://apify.com/silentshadow55/electricity-plans-actor.md - **Developed by:** [Esteban Ortega](https://apify.com/silentshadow55) (community) - **Categories:** Lead generation, Automation - **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $8.00 / 1,000 efl parseds This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Texas Electricity Plans Scraper — Power to Choose + EFL Parser Scrape **every retail electricity plan offered for any Texas ZIP code** from [Power to Choose](https://www.powertochoose.org) (the PUCT's official comparison site) — and go far beyond the listing: this Actor **downloads each plan's Electricity Facts Label (EFL) PDF and parses it into structured rate data** that exists nowhere else as an API. The headline "average price per kWh" on Power to Choose is famously misleading — it's calculated at exactly 500, 1000, or 2000 kWh and hides base charges, usage-credit cliffs, and minimum-usage fees. The real pricing lives inside each plan's EFL PDF. This Actor reads all of them for you. ### What you get per plan **From Power to Choose** (every plan, every ZIP): - Provider, plan name, TDU service territory, rate type (fixed/variable/indexed) - Contract term, prepaid / time-of-use flags, renewable % - Advertised average prices at 500 / 1000 / 2000 kWh - Enrollment URL and phone, EFL / Terms of Service / YRAC document links **Parsed from the EFL PDF** (the differentiator): - ⚡ **Energy charge** in ¢/kWh — including tiered rates - 💵 **Base monthly charge** (or per-day charge) - 🔌 **TDU delivery charges** — the pass-through ¢/kWh and $/month - 🎁 **Bill credits** — amount + the usage threshold that triggers them (the "$125 credit at 1000+ kWh" cliffs that dominate Texas pricing) - ⚠️ **Minimum usage fees** and their thresholds - 🚪 **Early termination fee** — flat or per-month-remaining - 📅 EFL issue date, contract term, renewable content **Computed for you:** - `cost_at_usage` — **true monthly cost at YOUR usage level** (e.g. 1,200 kWh), not just the mandated 500/1000/2000 points - `monthly_cost_500/1000/2000_usd` — true dollar cost at the standard points - `validation` — every parsed plan is **self-validated** by recomputing the 1000 kWh average price from components and comparing it to the EFL's own stated table - `parse_confidence` — high / medium / low, so you know exactly which records to trust blindly ### Example output ```json { "zip_code": "78045", "tdu": "AEP TEXAS CENTRAL", "provider": "RHYTHM", "plan_name": "Rhythm Max Saver 12", "rate_type": "Fixed", "term_months": 12, "avg_price_1000_cents": 7.8, "energy_charge_cents_per_kwh": 14.648, "base_charge_monthly_usd": 0.0, "tdu_cents_per_kwh": 5.8272, "tdu_monthly_usd": 3.24, "bill_credits": [ { "amount_usd": 125.0, "min_kwh": 1000, "max_kwh": null }, { "amount_usd": 5.0, "min_kwh": null, "max_kwh": null } ], "early_termination_fee_usd": 150.0, "etf_type": "flat", "cost_at_usage": { "usage_kwh": 1200, "monthly_cost_usd": 118.94, "effective_cents_per_kwh": 9.91, "method": "components" }, "validation": { "recomputed_avg_1000_cents": 7.79, "stated_avg_1000_cents": 7.8, "within_tolerance": true }, "parse_confidence": "high", "enroll_url": "https://..." } ```` ### Who uses this - **Electricity comparison and switching sites** — power your rankings with real component data instead of the misleading advertised averages - **Retail electricity providers (REPs)** — monitor competitors' rate structures, credits, and ETFs daily across every TDU territory - **Energy brokers and consultants** — quote against the live market for any customer usage profile - **Bill-audit and home-services apps** — "you'd save $412/yr on plan X" requires exactly this data - **Researchers and journalists** — track teaser-rate structures and usage-credit cliffs across the deregulated market - **AI agents** — ask "cheapest 12-month fixed plan for 1,400 kWh/mo in Houston" and get a grounded answer (MCP-ready) ### Input ```json { "zipCodes": ["75201", "77002"], "monthlyUsageKwh": 1200, "parseEfl": true, "rateTypes": ["Fixed"], "maxTermMonths": 12 } ``` Filter by rate type, term length, provider, TDU territory (Oncor, CenterPoint, AEP Central/North, TNMP, Lubbock — useful for split ZIPs and multi-ZIP runs), renewable %, prepaid/time-of-use. Set `parseEfl: false` for a fast listing-only run. ### Data quality, honestly - All plans returned by Power to Choose are included; ~90% of EFLs are direct PDFs that parse cleanly. A few providers serve JS-only EFL viewers — those plans are flagged `efl_status: "js_viewer_unsupported"` and still carry full listing data plus interpolated cost estimates. - Component-based cost math is used **only when it reproduces the EFL's own stated average price within 0.5¢ at all three of the 500 / 1000 / 2000 kWh anchors** (`validation.within_tolerance`, with the per-anchor detail in `validation.anchors_checked`). Checking every anchor — not just 1000 — catches a dropped usage tier or a mis-scoped bill credit that would otherwise slip through. If any anchor fails or a computed cost is implausible, the Actor falls back to interpolating the official average-price points — you never get a garbage number presented as truth. - Time-of-use plans (free nights/weekends) always use interpolation, since their pricing depends on load shape. ### Usage notes - Runs read public regulatory disclosures from the PUCT's official site and the providers' own document servers. - Typical run: one ZIP with full EFL parsing ≈ 150 plans in 1–2 minutes. - Non-deregulated ZIPs (Austin, San Antonio, El Paso, co-op territory) return zero plans — that's the market, not a bug. ### FAQ **Is there an official Power to Choose API?** No. Power to Choose offers only a CSV export with the headline average prices — no rate components, no credits, no fees. This Actor is the closest thing to a full **Power to Choose API**: run it on demand or on a schedule and get every plan as JSON, CSV, or Excel via the Apify API, including the parsed EFL rate structure that exists nowhere else in machine-readable form. **What is an Electricity Facts Label (EFL)?** The PUCT-mandated disclosure PDF behind every Texas electricity plan. It contains the *actual* pricing — energy charge, base charge, TDU delivery charges, bill-credit thresholds, minimum-usage fees, and the early termination fee. The advertised "average price per kWh" is computed from it at exactly 500/1000/2000 kWh, which is why plans that look cheapest are often the most expensive at your real usage. **Why is the advertised average price misleading?** Many plans stack a large bill credit (e.g., $125 at 1000+ kWh) on top of a high energy charge. At exactly 1000 kWh they look like 7¢/kWh; at 900 kWh the credit vanishes and the same plan costs 40% more. This Actor computes the true monthly cost at *your* usage level from the parsed components. **Which cities and ZIP codes does it cover?** All deregulated ERCOT territories: Dallas–Fort Worth (Oncor), Houston (CenterPoint), Corpus Christi, Laredo, McAllen and south Texas (AEP Texas), Abilene, Midland–Odessa, and more — roughly 85% of Texas by population. Austin, San Antonio, and El Paso are served by municipal utilities and return no plans. **How fresh is the data?** Live — every run pulls the current Power to Choose listings and the current EFL PDFs at that moment. Schedule it daily to track rate changes, new plans, and credit-structure changes. **Can I export to CSV, Excel, or JSON?** Yes — every run's dataset is downloadable in JSON, CSV, XLSX, and XML, or consumable programmatically through the Apify API and integrations (Google Sheets, webhooks, Make, Zapier, LangChain). **Can AI agents use this?** Yes. The Actor works with Apify's MCP server, so agents like Claude or ChatGPT can answer questions such as "cheapest 12-month fixed plan for 1,400 kWh/month in Houston" with grounded, current data. **Is this legal?** The Actor reads public regulatory disclosures: the PUCT's official comparison listings and the EFL documents providers are required by law to publish. ### Roadmap - Headless fallback for JS-only EFL viewers - Commercial plan support - Other deregulated states: Ohio (Apples to Apples), Pennsylvania (PA Power Switch), Illinois, Connecticut Questions or a provider whose EFL parses poorly? Open an issue — parser coverage improves fastest with real examples. # Actor input Schema ## `zipCodes` (type: `array`): One or more Texas ZIP codes in the deregulated ERCOT market (e.g. Dallas 75201, Houston 77002, Laredo 78045). ZIPs served by municipal utilities or co-ops (Austin, San Antonio) return no plans. ## `parseEfl` (type: `boolean`): Download and parse each plan's Electricity Facts Label PDF into structured rate components (energy charge, base charge, TDU charges, bill credits, termination fee). Turn off for a faster, cheaper run with only the Power to Choose listing data. ## `monthlyUsageKwh` (type: `integer`): Monthly consumption used to compute the true cost of every plan (cost\_at\_usage). Texas residential average is about 1,200 kWh. ## `rateTypes` (type: `array`): Only include these rate types. Leave empty for all. ## `minTermMonths` (type: `integer`): Only include plans with a contract term of at least this many months. 0 = no minimum. ## `maxTermMonths` (type: `integer`): Only include plans with a contract term of at most this many months. 0 = no maximum. ## `includePrepaid` (type: `boolean`): Include prepaid / pay-as-you-go plans in the results. ## `includeTimeOfUse` (type: `boolean`): Include time-of-use plans such as free-nights or free-weekends offers. Their cost estimates always use the official average-price points, since true cost depends on when you use power. ## `minRenewablePct` (type: `integer`): Only include plans with at least this renewable percentage. ## `providers` (type: `array`): Only include plans whose retail provider name contains one of these strings (case-insensitive), e.g. "TXU", "Reliant". Leave empty for all providers. ## `tdus` (type: `array`): Only include plans delivered by these TDUs. A ZIP almost always maps to a single TDU, so this mainly matters for split ZIPs and multi-ZIP runs where you want one utility territory only (e.g. Oncor). Leave empty for all TDUs. ## `maxPlansPerZip` (type: `integer`): Cap the number of plans processed per ZIP code. 0 = no cap. ## `includeRawEflText` (type: `boolean`): Attach the full extracted EFL text to each item (large). Useful for auditing or feeding to an LLM. ## Actor input object example ```json { "zipCodes": [ "75201" ], "parseEfl": true, "monthlyUsageKwh": 1000, "minTermMonths": 0, "maxTermMonths": 0, "includePrepaid": true, "includeTimeOfUse": true, "minRenewablePct": 0, "maxPlansPerZip": 0, "includeRawEflText": false } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "zipCodes": [ "75201" ] }; // Run the Actor and wait for it to finish const run = await client.actor("silentshadow55/electricity-plans-actor").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "zipCodes": ["75201"] } # Run the Actor and wait for it to finish run = client.actor("silentshadow55/electricity-plans-actor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "zipCodes": [ "75201" ] }' | apify call silentshadow55/electricity-plans-actor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=silentshadow55/electricity-plans-actor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Texas Electricity Plans Scraper", "description": "Get every retail electricity plan for any Texas ZIP code from Power to Choose — plus what no one else offers: each plan's Electricity Facts Label PDF parsed into structured rates (energy charge, base charge, TDU fees, bill credits, ETF) and true monthly cost at your usage level.", "version": "0.0", "x-build-id": "ReGyh5yC3o7Am0YSJ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/silentshadow55~electricity-plans-actor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-silentshadow55-electricity-plans-actor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/silentshadow55~electricity-plans-actor/runs": { "post": { "operationId": "runs-sync-silentshadow55-electricity-plans-actor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/silentshadow55~electricity-plans-actor/run-sync": { "post": { "operationId": "run-sync-silentshadow55-electricity-plans-actor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "zipCodes" ], "properties": { "zipCodes": { "title": "Texas ZIP codes", "type": "array", "description": "One or more Texas ZIP codes in the deregulated ERCOT market (e.g. Dallas 75201, Houston 77002, Laredo 78045). ZIPs served by municipal utilities or co-ops (Austin, San Antonio) return no plans.", "items": { "type": "string" } }, "parseEfl": { "title": "Parse EFL PDFs", "type": "boolean", "description": "Download and parse each plan's Electricity Facts Label PDF into structured rate components (energy charge, base charge, TDU charges, bill credits, termination fee). Turn off for a faster, cheaper run with only the Power to Choose listing data.", "default": true }, "monthlyUsageKwh": { "title": "Your monthly usage (kWh)", "minimum": 100, "maximum": 10000, "type": "integer", "description": "Monthly consumption used to compute the true cost of every plan (cost_at_usage). Texas residential average is about 1,200 kWh.", "default": 1000 }, "rateTypes": { "title": "Rate types", "type": "array", "description": "Only include these rate types. Leave empty for all.", "items": { "type": "string", "enum": [ "Fixed", "Variable", "Indexed" ] } }, "minTermMonths": { "title": "Minimum term (months)", "minimum": 0, "maximum": 60, "type": "integer", "description": "Only include plans with a contract term of at least this many months. 0 = no minimum.", "default": 0 }, "maxTermMonths": { "title": "Maximum term (months)", "minimum": 0, "maximum": 60, "type": "integer", "description": "Only include plans with a contract term of at most this many months. 0 = no maximum.", "default": 0 }, "includePrepaid": { "title": "Include prepaid plans", "type": "boolean", "description": "Include prepaid / pay-as-you-go plans in the results.", "default": true }, "includeTimeOfUse": { "title": "Include time-of-use plans (free nights/weekends)", "type": "boolean", "description": "Include time-of-use plans such as free-nights or free-weekends offers. Their cost estimates always use the official average-price points, since true cost depends on when you use power.", "default": true }, "minRenewablePct": { "title": "Minimum renewable content (%)", "minimum": 0, "maximum": 100, "type": "integer", "description": "Only include plans with at least this renewable percentage.", "default": 0 }, "providers": { "title": "Provider filter", "type": "array", "description": "Only include plans whose retail provider name contains one of these strings (case-insensitive), e.g. \"TXU\", \"Reliant\". Leave empty for all providers.", "items": { "type": "string" } }, "tdus": { "title": "TDU (utility territory) filter", "type": "array", "description": "Only include plans delivered by these TDUs. A ZIP almost always maps to a single TDU, so this mainly matters for split ZIPs and multi-ZIP runs where you want one utility territory only (e.g. Oncor). Leave empty for all TDUs.", "items": { "type": "string", "enum": [ "Oncor", "CenterPoint", "AEP Texas Central", "AEP Texas North", "Texas-New Mexico", "Lubbock" ], "enumTitles": [ "Oncor Electric Delivery (Dallas-Fort Worth, West TX)", "CenterPoint Energy (Houston metro)", "AEP Texas Central (Corpus Christi, Laredo, Rio Grande Valley)", "AEP Texas North (Abilene, San Angelo)", "TNMP — Texas-New Mexico Power (Gulf Coast, West TX pockets)", "Lubbock Power & Light" ] } }, "maxPlansPerZip": { "title": "Max plans per ZIP", "minimum": 0, "type": "integer", "description": "Cap the number of plans processed per ZIP code. 0 = no cap.", "default": 0 }, "includeRawEflText": { "title": "Include raw EFL text", "type": "boolean", "description": "Attach the full extracted EFL text to each item (large). Useful for auditing or feeding to an LLM.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```