# Transmission Line & Substation Distance API by Coordinates (`malonestar/hifld-grid-proximity-screener`) Actor

For each lat/lon site: distance to the nearest transmission line (kV, owner, overhead/underground), nearest substation, nearest power plant, the serving utility and its ISO/RTO, plus generation and battery-storage MW nearby. Includes sub-100 kV. Data-center, renewable, BESS and EV siting.

- **URL**: https://apify.com/malonestar/hifld-grid-proximity-screener.md
- **Developed by:** [Kyle Maloney](https://apify.com/malonestar) (community)
- **Categories:** Agents, Developer tools, Lead generation
- **Features:** Limited permissions
- **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.50 / 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.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## Nearest Transmission Line & Substation Finder by Lat/Lon

Answers **"how far is this site from transmission and a substation, and who serves it?"** for a whole list of sites at once. For every lat/lon you get the **distance to the nearest transmission line** (kV, owning utility, overhead vs underground), the **nearest substation to those coordinates**, the nearest power plant, how much generation and **battery storage** sits within the radius, **which utility serves this address** and its **ISO/RTO** — plus a HIGH/MEDIUM/LOW grid-access tier you can sort a portfolio by. Built for **data center site power availability** screening, **BESS interconnection site screening**, and renewable **grid capacity site selection**.

### What's new in v1.3 (the accuracy fix is now enforced at runtime)

v1.2 fixed the truncated-layer defect below, but nothing **checked** that the fix stayed fixed, and a fallback to the old truncated layer still produced a billable row that looked complete. v1.3 closes both.

**A live drift gate now runs before any billable row.** Every run measures the national line layer and asserts it still contains sub-100 kV circuits — the exact property the truncated copy lacks. Measured live: the healthy layer returns **94,619** lines of which **27,277** are below 100 kV; the truncated copy returns 52,244 and **zero**. If that regresses, the run **fails and bills nothing** rather than quietly selling 4x-overstated distances. The measurements ride on every row (`lines_total_count_measured`, `lines_sub100kv_count_measured`), so you can audit the check itself. An offline test cannot catch this — a fixture built from a truncated source looks perfectly healthy — which is precisely why it is a live assertion.

**A degraded answer is now degraded in the fields, not just in a log line.** If the complete layer is unreachable, v1.2 fell back to the truncated 2023 copy, warned in the log, and billed a row whose `nearest_line_distance_miles` was indistinguishable from a verified one. Now that run **fails by default and bills nothing**. Set `allowTruncatedLineFallback: true` to get rows anyway — in which case every field that would be a claim about the complete grid is **null**, `grid_tier` reads `DEGRADED`, and only the `nearest_ge100kv_line_*` columns (the one question the truncated layer can honestly answer) are populated.

**Every optional layer now reports its own outcome** — `substations_status`, `power_plants_status`, `utility_status`, `planned_status` — so "no substation nearby" is distinguishable from "the substation layer was down". A null is no longer ambiguous.

**New `nearest_ge100kv_line_*` columns** give the nearest transmission-grade (>=100 kV) circuit alongside the nearest circuit of any voltage, on every run.

**All 70 existing columns are unchanged** — verified cell-by-cell against v1.2 on identical inputs: 490 cells compared, zero differences, zero removed fields, 16 added.

### What's new in v1.2 (important accuracy fix)

**v1.0–1.1 silently missed 44.8% of the national transmission network.** The layer they queried was a truncated copy containing **zero circuits below 100 kV** — every 69 kV / 46 kV / 34.5 kV sub-transmission line was invisible. That is exactly the **69 kV sub-transmission proximity** that mid-size solar, BESS and EV-charging projects actually interconnect to.

v1.2 moves to the complete national layer (94,619 records vs 52,244). Measured effect on real sites:

| Site | v1.1 reported | v1.2 reports | |
|---|---|---|---|
| Storm Lake, IA | 2.545 mi @ 161 kV, 2 lines | **0.649 mi @ 69 kV**, 21 lines | 3.9× overstated |
| Bend, OR | 1.204 mi @ 115 kV, 27 lines | **0.300 mi @ 69 kV**, 37 lines | 4.0× overstated |
| Ashburn, VA | 0.507 mi, 18 lines | 0.435 mi, 31 lines | |

Also new: **serving utility + ISO/RTO** per site, EIA's **monthly** power-plant inventory (the previous 2018 snapshot is missing the 766 MW Potomac Energy Center outside Ashburn entirely, and at Bend OR it sees 2 plants where EIA sees 5, including 29.8 MW of post-2018 solar), battery/solar/wind MW within the radius, honest substation naming, miles alongside kilometres, and a data-vintage stamp on every source. **All existing columns are unchanged** — v1.2 is purely additive.

### How it works

For every asset the actor runs a bounding-box query against the national transmission-line, substation and power-plant layers, plus a point-in-polygon lookup against electric retail service territories, then computes distances locally. Line distance is measured **perpendicular to the line geometry** (true point-to-segment, not to the nearest vertex or a centroid). One combined row is emitted per asset. No API key, no login.

Before any billable row, a **live drift gate** measures the national line layer and fails the run if it no longer contains the sub-100 kV circuits that distinguish it from the truncated copy. A bad coordinate produces an `ERROR` row for that asset only. If the primary line layer is unreachable, the run **fails and bills nothing** by default rather than serving the truncated fallback; `allowTruncatedLineFallback: true` opts into explicitly `DEGRADED` rows instead. If **every** asset fails, the run fails outright and **nothing is billed**.

#### Grid-access tier (editorial model)

| Tier | Rule |
|---|---|
| HIGH | An existing line ≥ 230 kV within 2 miles |
| MEDIUM | Existing ≥ 115 kV within 2 miles, or ≥ 230 kV within 5 miles |
| LOW | Any existing line within the search radius |
| NONE | No existing line within the search radius |
| ERROR | Asset could not be screened (see `error`) |
| DEGRADED | The line universe was incomplete, so no tier can honestly be asserted (opt-in fallback only; see v1.3 above) |

"Existing" means energized lines, excluding those whose STATUS marks them under construction, proposed or retired. Most existing lines are tagged `NOT AVAILABLE` rather than `IN SERVICE`, so this screener treats `NOT AVAILABLE` as existing — a strict `IN SERVICE`-only filter would wrongly report NONE next to real 230 kV lines. Only 65 of 52,244 records nationally carry a genuinely non-operational status, so `lines_under_construction_within_radius` is 0 for almost every site. The tier is a heuristic for ranking sites, not an interconnection or hosting-capacity study.

### Example input

```json
{
  "assets": [
    { "lat": 39.0170, "lon": -77.4600, "label": "Ashburn VA data center site" },
    { "lat": 42.6414, "lon": -95.2097, "label": "Storm Lake IA site" }
  ],
  "radiusMiles": 10,
  "includeSubstations": true,
  "includePowerPlants": true,
  "includeUtility": true
}
```

Tip on radius: 5 miles is a tight transmission screen, but generation is sparser than transmission, so a 5-mile circle often contains no power plant at all and the whole `nearest_power_plant_*` / `generation_mw_within_radius` block comes back null. Both sites above are exactly that case — the nearest plant to Ashburn (the 766 MW Potomac Energy Center) is 5.37 miles out. Use 10 miles or more when you care about the generation and storage columns.

### Output fields (one combined row per asset)

| Field | Meaning |
|---|---|
| `asset_label`, `asset_lat`, `asset_lon` | Your site, echoed back |
| `nearest_line_distance_miles` | **Distance to nearest transmission line**, perpendicular to the line geometry |
| `nearest_line_voltage_kv` | Its voltage in kV; null when the source reports the unknown sentinel (14,248 of 94,619 records) |
| `nearest_line_volt_class` | Voltage class: `UNDER 100`, `SUB 100`, `100-161`, `220-287`, `345`, `500`, `735 AND ABOVE`, `DC`, `Unknown` |
| `nearest_line_owner` | Owning utility (null on the ~17% of records that don't report one) |
| `nearest_line_status` | Raw status (`NOT AVAILABLE` = unspecified, **not** out of service) |
| `nearest_line_type` | `AC; OVERHEAD` / `AC; UNDERGROUND` / `DC; …` — underground tap costs differ materially |
| `nearest_line_geometry_inferred` | true when the alignment was inferred, not surveyed — a confidence flag on the distance |
| `nearest_line_substation_a`, `nearest_line_substation_b` | The two substations the circuit connects. null when the source carries only a numbered `UNKNOWN146360` placeholder — 43% of records for the A end, 22% for the B end |
| `lines_within_radius` | Line-record count within radius (source segments, not distinct circuits) |
| `sub_transmission_lines_within_radius` | **69 kV sub-transmission proximity** — existing lines below 100 kV in range |
| `lines_under_construction_within_radius` | Of those, how many are flagged under construction |
| `max_voltage_within_radius_kv` / `max_existing_voltage_within_radius_kv` | Highest voltage in range, all statuses / existing only |
| `nearest_substation_name` | **Nearest substation to coordinates** — null when the source has only a numbered placeholder |
| `nearest_substation_named` | false = a substation was found but is unnamed upstream (vs no substation at all) |
| `nearest_substation_id` | Stable upstream ID, so an unnamed substation is still joinable and dedupable |
| `nearest_named_substation_name`, `nearest_named_substation_distance_miles` | The closest substation that actually **has** a name. Use this when `nearest_substation_name` is null — the single closest is often an unnamed placeholder while real named substations sit just behind it |
| `named_substations_within_radius` | How many substations in range have a real name |
| `nearest_substation_distance_miles` / `_distance_km` | Distance in both units |
| `nearest_substation_max_voltage`, `nearest_substation_min_voltage_kv` | Substation voltages. Both are sparse upstream: max voltage is null for 78% of substations and min voltage for 81% — see the FAQ |
| `nearest_substation_line_count` | Circuits terminating there — a better capacity proxy than max voltage. null when unreported (the source encodes unknown as 0 on 19% of substations; that is never emitted as a count) |
| `substations_within_radius` | Substation count within radius |
| `nearest_power_plant_name`, `nearest_power_plant_distance_miles`, `nearest_power_plant_distance_km`, `nearest_power_plant_fuel`, `nearest_power_plant_type`, `nearest_power_plant_capacity_mw`, `nearest_power_plant_sector` | Nearest plant (fuel e.g. `natural gas`, `solar`, `wind`, `batteries`) |
| `nearest_power_plant_eia_plant_code`, `nearest_power_plant_eia_utility_id` | EIA join keys into EIA-860 / EIA-923 |
| `power_plants_within_radius`, `generation_mw_within_radius` | Plant count and total MW in range |
| `battery_storage_mw_within_radius` | **Battery storage near my site**, in MW |
| `solar_mw_within_radius`, `wind_mw_within_radius` | Solar / wind MW in range |
| `serving_utility_name` | **Which utility serves this address** |
| `serving_utility_eia_id` | **Utility service territory API** join key (EIA utility ID) |
| `serving_utility_type`, `serving_utility_regulated`, `holding_company`, `serving_utility_state` | Ownership, regulation, parent |
| `utility_customers`, `utility_summer_peak_mw`, `utility_summer_capacity_mw` | Utility scale (EIA-861) |
| `balancing_authority_code`, `iso_rto`, `market_type` | **ISO RTO territory lookup by lat long**: PJM, ERCOT, CAISO, MISO, SPP, ISO-NE, NYISO |
| `overlapping_utility_count` | How many territories cover the point (>1 is common) |
| `state_industrial_price_cents_kwh`, `state_commercial_price_cents_kwh`, `electricity_price_period`, `electricity_price_scope` | Optional EIA state price (needs a free key) |
| `planned_line_nearby` | Low-confidence, non-authoritative hint (opt-in; see FAQ) |
| `grid_tier` | `HIGH` / `MEDIUM` / `LOW` / `NONE` / `ERROR` |
| `lines_source`, `lines_data_vintage`, `substation_data_vintage`, `generation_data_period`, `utility_data_year` | Which layer served the row and how current each source is |
| `nearest_ge100kv_line_distance_miles`, `nearest_ge100kv_line_voltage_kv`, `nearest_ge100kv_line_owner` | **v1.3** — nearest transmission-grade (>=100 kV) circuit, alongside the nearest circuit of any voltage |
| `ge100kv_lines_within_radius` | **v1.3** — count of >=100 kV lines in range |
| `lines_status` | **v1.3** — `ok`, `degraded_truncated`, or `unavailable_truncated_fallback_refused` |
| `lines_complete_universe` | **v1.3** — true when the nearest-line fields were computed over the complete national layer. When false, those fields are null rather than misleading |
| `lines_degraded_reason` | **v1.3** — why the line answer is incomplete, when it is; null on a healthy row |
| `substations_status`, `power_plants_status`, `utility_status`, `planned_status` | **v1.3** — per-layer outcome: `ok` / `unavailable` / `not_requested`, so a null is never read as a verified negative |
| `lines_drift_gate_status` | **v1.3** — `verified` or `unavailable`. A failed gate fails the whole run and emits nothing |
| `lines_total_count_measured`, `lines_sub100kv_count_measured`, `lines_negative_control_count` | **v1.3** — what the drift gate actually measured this run (healthy: 94,619 / 27,277 / 0). Audit the check itself |
| `lines_gate_note` | **v1.3** — note from the gate, e.g. which probe could not complete; null when cleanly verified |
| `error`, `checked_at`, `source_url` | Error message, run timestamp, source layer |

### Serving utility, ISO/RTO and market

For each site the actor resolves the retail electric service territory containing the point. Territories genuinely overlap — Phoenix returns 12, Dallas 5 — so the actor picks a **primary**: the largest by summer peak load, excluding federal power marketers. Verified to select Oncor at Dallas, Arizona Public Service at Phoenix, PG\&E at San Jose and Virginia Electric & Power at Ashburn.

The balancing-authority code is then mapped to one of the seven US organized markets. `iso_rto` is null in vertically integrated territory, which is itself the answer — it tells you there is no ISO interconnection queue to enter. This pairs directly with an interconnection-queue tracker keyed on the same seven ISOs.

**Field reliability, measured across all 2,931 territories:** utility name and EIA ID 100%, balancing authority 96.7%, customers 99.2%, summer peak 42.5%, ownership type 42.5%, regulated status 22.7%, summer capacity 21.5%. Do **not** compute a reserve margin from capacity minus peak — capacity is present on barely a fifth of records.

### Generation and storage nearby

Power-plant data comes from EIA's monthly operable-generator inventory (13,446 plants), refreshed far more often than the static critical-infrastructure snapshots most grid tools use. Beyond the nearest plant you get total generation MW in range broken out by battery, solar and wind — the strongest co-location signal for a data-centre or BESS developer, and impossible to answer from a 2018 snapshot that predates essentially the entire US grid-battery fleet.

### Optional: electricity price

Supply a free [EIA API key](https://www.eia.gov/opendata/register.php) as `eiaApiKey` to populate `state_industrial_price_cents_kwh` and `state_commercial_price_cents_kwh` (latest month, ~2-month lag). **No key is required** — leave it empty and those two columns are null while everything else runs normally. One lookup per distinct state, not per site. These are **state-by-sector averages, not the specific utility tariff** — `electricity_price_scope` says so on every row.

### Who uses it

- Data-center site selectors screening candidate parcels for **data center site power availability** before spending on interconnection studies.
- Solar, wind and BESS developers ranking parcels by **grid capacity site selection** and the voltage class they can realistically tie into.
- EV-charging network planners verifying grid presence and sub-transmission access around candidate hubs.
- Land agents adding grid-access, nearest-substation and serving-utility columns to listing sheets.
- Energy analysts looking at line density, ownership, fuel mix and market structure around a point.

### Use from an AI agent: quickstart

The smallest input that returns a real answer. Verified live on 2026-10-05: the run SUCCEEDED and returned 1 row in about 10 seconds.

```json
{
  "assets": [
    {
      "lat": 39.017,
      "lon": -77.46,
      "label": "Ashburn VA site"
    }
  ]
}
```

**Call it** through the hosted MCP server (`https://mcp.apify.com?tools=malonestar/hifld-grid-proximity-screener`) or straight over HTTP:

```
POST https://api.apify.com/v2/acts/malonestar~hifld-grid-proximity-screener/run-sync-get-dataset-items
Authorization: Bearer YOUR_APIFY_TOKEN
Content-Type: application/json
```

with the JSON above as the body. The response is a JSON array of dataset rows.

**What comes back:** exactly one row per site. Abbreviated first row from that run (the full row has 86 fields, all described in the output schema):

```json
{
  "asset_label": "Ashburn VA site",
  "nearest_line_distance_miles": 0.435,
  "nearest_line_voltage_kv": null,
  "nearest_line_owner": "VIRGINIA ELECTRIC & POWER CO",
  "lines_within_radius": 31,
  "nearest_substation_name": null,
  "serving_utility_name": "VIRGINIA ELECTRIC & POWER CO",
  "iso_rto": "PJM",
  "grid_tier": "HIGH",
  "lines_status": "ok"
}
```

**Read before you conclude anything:** `lines_status`, `substations_status`, `utility_status` and `lines_complete_universe`. A layer that could not be read is reported as such; a `null` distance means "not checked", not "no line nearby".

**Input notes for agents**

- `assets` is an array of `{ "lat": number, "lon": number, "label": "optional" }` (also accepts `"lat,lon"` strings).
- A malformed site produces an `error` row for that site and the run continues.

**Cost:** $0.010 per row at the Free-tier list price (paid plans get a discount), so the example above costs about $0.010. A run that cannot answer fails and bills no rows.

### Use as an MCP tool

This Actor is callable directly by any MCP-compatible AI agent through Apify's hosted
MCP server. There is no server to run and no integration code to write - the tool
schema an agent sees is generated from this Actor's own input and dataset schemas.

**Endpoint**

```
https://mcp.apify.com?tools=malonestar/hifld-grid-proximity-screener
```

**Claude Desktop, Claude Code or Cursor** - add to `claude_desktop_config.json`,
`.mcp.json` or `.cursor/mcp.json` respectively:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=malonestar/hifld-grid-proximity-screener",
      "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" }
    }
  }
}
```

Get a token at https://console.apify.com/settings/integrations. Claude Desktop can
also authenticate interactively via OAuth against `https://mcp.apify.com` with no
`headers` block. Full reference: https://docs.apify.com/platform/integrations/mcp

**Try asking your agent**

> For these four candidate solar sites, how far is the nearest transmission line, what voltage is it, and which utility and ISO would serve them?

**Chains well with** - expose these alongside it by comma-separating the `tools`
parameter, and the agent can carry results from one into the next:

- `malonestar/interconnection-queue-tracker`
- `malonestar/site-due-diligence-bundle`
- `malonestar/epa-contaminated-site-screener`

```
https://mcp.apify.com?tools=malonestar/hifld-grid-proximity-screener,malonestar/interconnection-queue-tracker,malonestar/site-due-diligence-bundle,malonestar/epa-contaminated-site-screener
```

Billing is unchanged when called as an MCP tool: this Actor is Pay-Per-Event and an
agent pays the same per-result price a human does. A run that cannot answer fails
without billing rather than returning an unverified negative.

#### Was this useful?

If a run answered your question, a short review on this Store page helps other buyers find the Actor; every published review is read. If a run gave a wrong or confusing answer, open an Issue on this page with the run ID and it will be treated as a defect, not feedback.

### FAQ

**Is there a distance to nearest electric substation API?** Yes — every screened asset returns `nearest_substation_distance_miles`, `nearest_substation_distance_km`, `nearest_substation_name`, `nearest_substation_line_count` and `nearest_substation_max_voltage`, on by default.

**Can I do substation proximity screening for data centers in bulk?** Yes — submit up to 2,000 sites per run as `assets` and get one row per site.

**Which utility serves this address, and what ISO is it in?** `serving_utility_name` and `iso_rto` answer both from a lat/lon, with `serving_utility_eia_id` as the join key into EIA data.

**Does it include sub-transmission (69 kV and below)?** Yes, since v1.2 — see `sub_transmission_lines_within_radius`. Set `minVoltageKv` to 115 or 230 if you only want high-voltage access.

**Which columns are commonly null, and why?** Substation `max_voltage` (78% null upstream), `min_voltage_kv` (81%), `name` (62% placeholders — use `nearest_named_substation_name`), and line `substation_a`/`_b` (43%/22% placeholders). The four electricity-price columns need an optional EIA key; `planned_line_nearby` needs `includePlanned: true`; `error` is null on every successful row by design. Nothing else should be null across a batch — if a whole block is, the radius is likely too tight.

**Why is `nearest_substation_max_voltage` often null?** Because the only national public substation dataset does not publish it for **78% of substations**, and 62% carry a numbered placeholder instead of a real name. Rather than emit `UNKNOWN30442` as if it were a name, this actor nulls it and sets `nearest_substation_named: false`, and gives you `nearest_named_substation_name` (the closest substation that *does* have a name), `nearest_substation_id` (a stable identifier you can still join on), and `nearest_substation_line_count` as a more reliable capacity proxy. That layer is a 2018 snapshot — `substation_data_vintage` says so on every row. No fresher national substation service exists publicly; we report the limitation instead of hiding it.

**Is the distance exact?** The math is exact: distances are measured perpendicular to the published geometry, accurate to a few feet at screening scales. The *geometry* is a separate question — 62% of line records are flagged as inferred rather than surveyed, which is why `nearest_line_geometry_inferred` is on every row. Treat a flagged line's distance as approximate.

**Does it include planned transmission lines?** Only as an opt-in, non-authoritative hint. The planned-line layer is an editable scratch layer with geometry only (no owner/voltage/status). Set `includePlanned: true` to populate `planned_line_nearby` and treat it as a weak signal.

**Where does the data come from?** Public, keyless ArcGIS FeatureServers: the national electric power transmission lines layer hosted by Esri's Federal user community (2025-08), electric substations mirrored on FEMA's ArcGIS Online org (2018-04), EIA's US power plants inventory (monthly), and HIFLD electric retail service territories (2025-08). Vintages differ by source and are stamped on every row. This is advisory data — confirm with the utility before committing capital.

**How is it billed?** One result per screened asset. Assets that fail to screen are emitted as ERROR rows unless you set `skipErrorRows: true`; a run in which **every** asset fails is failed outright and bills nothing.

### Telemetry

This actor can send one usage record per run to the publisher: the channel the run was started from (Console, API, MCP, scheduler, ...), a timestamp, the build number, a salted one-way hash of the account id (so repeat use can be counted without storing the id itself), and the NAMES of the input fields used. It never records input values, results or the account id, and it is used only to see how buyers reach the actor. It cannot slow the run by more than 3 seconds and can never affect your results or your bill.

# Actor input Schema

## `assets` (type: `array`):

Sites to screen for grid access. Each entry is an object { "lat": number, "lon": number, "label": "optional name" }. Also accepts "lat,lon" strings or \[lat, lon] arrays. One dataset row (one billed result) is produced per asset; a bad entry yields an ERROR row and the run continues.

## `radiusMiles` (type: `integer`):

Radius around each asset to search for transmission lines, substations and power plants, in miles (1-50). Features beyond this distance are ignored. Default 5.

## `minVoltageKv` (type: `integer`):

Optional. Only count/consider transmission lines at or above this many kV. Since v1.2 the underlying layer includes sub-100 kV sub-transmission (69/46/34.5 kV), so values below 100 are now meaningful — leave empty to include every line, or set 115/230 to screen for high-voltage access only. Lines with an unknown voltage are excluded when this is set. Does not filter substations or power plants.

## `includeSubstations` (type: `boolean`):

Also report the nearest electric substation (name, distance, max/min voltage, connected line count) plus substations within the radius. On by default — set to false to skip substation screening and speed up large batches.

## `includePowerPlants` (type: `boolean`):

Also report the nearest power plant (name, distance, fuel, technology, capacity MW, EIA plant code) plus total generation, battery-storage, solar and wind MW within the radius. Sourced from EIA's monthly plant inventory. On by default — set to false to skip and speed up large batches.

## `includeUtility` (type: `boolean`):

Also resolve which retail electric utility serves each site, its ownership type, holding company, customer count and summer peak, plus the balancing authority and ISO/RTO (PJM, ERCOT, CAISO, MISO, SPP, ISO-NE, NYISO). Where service territories overlap, the largest utility by summer peak load is reported as primary. On by default — one extra lookup per site.

## `includePlanned` (type: `boolean`):

Advanced/opt-in. Also check a 'planned transmission line' scratch layer that carries NO owner/voltage/status metadata. It is NOT an authoritative planned-line dataset — the planned_line_nearby flag is a low-confidence 'a planned-line geometry exists nearby' hint only. Default false.

## `skipErrorRows` (type: `boolean`):

When true, assets that could not be screened are logged but not written to the dataset, so you are not billed for them. Default false, which keeps every asset accounted for as an ERROR row. Note that a run in which EVERY asset fails always fails outright and bills nothing, regardless of this setting.

## `eiaApiKey` (type: `string`):

Optional. A free EIA API key (https://www.eia.gov/opendata/register.php) enables the state industrial and commercial electricity price columns. Everything else works without it — leave this empty and those two columns are simply null. One lookup per distinct state, not per site.

## `maxResults` (type: `integer`):

Maximum number of assets processed in one run (1-2000). One result row is emitted (and billed) per asset. Default 500.

## `allowTruncatedLineFallback` (type: `boolean`):

The transmission-line answer comes from a national layer of 94,619 lines. If that layer is unavailable, the only backup is a 2023 copy that contains NO line below 100 kV — 44.8% of the US grid, and the sub-transmission most mid-size solar, BESS and EV-charging projects actually interconnect to. At Storm Lake IA it reports the nearest line 2.545 mi away at 161 kV when the truth is 0.649 mi at 69 kV. By default (false) such a run FAILS and bills nothing. Set true to receive rows instead, in which every complete-universe field (nearest_line_distance_miles, lines_within_radius, max_voltage_within_radius_kv, ...) is null, grid_tier reads DEGRADED, and only the nearest_ge100kv_line\_\* columns are populated.

## `simulateOutage` (type: `string`):

Diagnostic seam for verifying the reliability behaviour on demand rather than waiting for a real outage. "none" (default) is a genuine no-op. "primary" forces the primary line layer to appear down; "drift" forces the live drift gate to measure a truncated layer (the run then fails and bills nothing); "gate" forces the drift probes to be unreachable; "both" combines primary and gate. Leave as none for normal use.

## Actor input object example

```json
{
  "assets": [
    {
      "lat": 39.017,
      "lon": -77.46,
      "label": "Ashburn VA data center site"
    },
    {
      "lat": 33.4484,
      "lon": -112.074,
      "label": "Phoenix AZ site"
    }
  ],
  "radiusMiles": 10,
  "includeSubstations": true,
  "includePowerPlants": true,
  "includeUtility": true,
  "includePlanned": false,
  "skipErrorRows": false,
  "maxResults": 500,
  "allowTruncatedLineFallback": false,
  "simulateOutage": "none"
}
```

# Actor output Schema

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

The default dataset (one row per asset).

# 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 = {
    "assets": [
        {
            "lat": 39.017,
            "lon": -77.46,
            "label": "Ashburn VA data center site"
        },
        {
            "lat": 33.4484,
            "lon": -112.074,
            "label": "Phoenix AZ site"
        }
    ],
    "radiusMiles": 10,
    "includeSubstations": true,
    "includePowerPlants": true,
    "includeUtility": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("malonestar/hifld-grid-proximity-screener").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 = {
    "assets": [
        {
            "lat": 39.017,
            "lon": -77.46,
            "label": "Ashburn VA data center site",
        },
        {
            "lat": 33.4484,
            "lon": -112.074,
            "label": "Phoenix AZ site",
        },
    ],
    "radiusMiles": 10,
    "includeSubstations": True,
    "includePowerPlants": True,
    "includeUtility": True,
}

# Run the Actor and wait for it to finish
run = client.actor("malonestar/hifld-grid-proximity-screener").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 '{
  "assets": [
    {
      "lat": 39.017,
      "lon": -77.46,
      "label": "Ashburn VA data center site"
    },
    {
      "lat": 33.4484,
      "lon": -112.074,
      "label": "Phoenix AZ site"
    }
  ],
  "radiusMiles": 10,
  "includeSubstations": true,
  "includePowerPlants": true,
  "includeUtility": true
}' |
apify call malonestar/hifld-grid-proximity-screener --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,malonestar/hifld-grid-proximity-screener"
        }
    }
}
```

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/ha3s0JeE7I67QTIWp/builds/qsp4EDW9AKTcvkze5/openapi.json
