# PowerGridIQ

> The PGIQ Rating is a proprietary, peer-calibrated view of where to site or schedule a large
> electricity load (data centers, AI compute clusters, heavy industry), covering 84 global power
> markets and sub-regions. It is built for AI agents that need a reasoned, cited answer rather
> than raw grid data.

PowerGridIQ scores five pillars (Access, Availability, Cost, Momentum, Carbon) per market, assigns a
tier (1 Prime to 5 Largely closed) and an outlook, and backs each with evidence and sources. Use the
JSON API below to get the rating, compare markets, or get a ranked "best market" decision.

## What is free vs paid
- Free, and citable: our opinion and the current read of any single market. Every rating page, all five
  pillar scores, the reliability overlay, the outlook, cited evidence, methodology, track record, and each
  market's own realized cost band and connection-friction level. Best entry points for agents: the per-market
  rating pages, https://powergridiq.com/methodology , and https://powergridiq.com/track-record .
- Paid: the compiled cross-market asset and the dimension of time. Ranked side-by-side tables with precise
  figures, exports, history, quarter-over-quarter change logs, alerts, and full machine access. Our full read of
  any single market, its own numbers included, is always free; the compiled cross-market ranking with precise
  figures, the time series, change logs, and alerts are paid.

## Auth & limits
- Free tier: no key, 100 requests/day per IP. Good for discovery and low-volume agents.
- Paid plans (self-serve, instant): the Analyst Desk $600/mo is the seat for people who research or decide
  where large loads should go (it includes the quarterly book The Global Energy Report, shortlist alerts,
  the full compiled cross-market tables, and full API and MCP access). For machines, pick by request volume:
  Developer $29/mo (25,000 requests) or Pro $199/mo (500,000 requests). Subscribe at
  https://powergridiq.com/build#pricing and the key is issued and emailed the moment you pay. Send it as
  `Authorization: Bearer pk_live_...`.
- Every metered response carries `X-PGIQ-Tier`, `X-PGIQ-RateLimit-Limit`, `X-PGIQ-RateLimit-Remaining`.
  Over quota returns HTTP 429. Check your own usage at GET /api/v1/usage (with your key).

## API (JSON, CORS-open, no key for the free tier)
- GET https://powergridiq.com/api/v1/meta : methodology, tiers, pillar weights, lenses, provenance.
- GET https://powergridiq.com/api/v1/markets : compact list of all rated markets.
- GET https://powergridiq.com/api/v1/ratings/{market} : full rating + evidence for one market (id, e.g. "quebec").
- GET https://powergridiq.com/api/v1/ratings : all ratings in one call. Single-market fields (tier, pillars, outlook, evidence) are free; the compiled fields (each market's realized_cost band and precise queue wait_months across all markets at once) require a paid key. Fetch any one market in full, free, at /api/v1/ratings/{market}.
- GET https://powergridiq.com/api/v1/best?lens=default|cost|carbon|momentum&group=us|europe|...&min_tier=3&limit=5 : ranked decision.
- GET https://powergridiq.com/api/v1/developments?market={id} : cited, dated grid developments.
- GET https://powergridiq.com/api/v1/actions?market={id} : rating-action history.
- GET https://powergridiq.com/api/v1/grid/{market} : grid snapshot (average operational carbon intensity, price, fuel mix, demand, and a system-level firm margin estimate; this is not local connectable capacity).
- GET https://powergridiq.com/api/v1/cheapest-window?market={id} : typical cheapest hours to run a flexible load (modelled daily price shape).
- GET https://powergridiq.com/api/v1/queue : interconnection-queue depth (GW) and a wait band per market (free). The precise typical wait in months and full per-market detail (historical withdrawal rate, data-center share, sources) require a paid key: GET /api/v1/queue/{market}.
- Global Interconnection Ledger, a continuously recorded time series of large-load grid-connection reality (queue depth and connection wait per market, captured weekly from operators worldwide, with what moved). Headline capture record is free: https://powergridiq.com/api/v1/ledger . The granular per-source capture index and per-market observation series are part of a paid plan. Story at https://powergridiq.com/interconnection-ledger .
- Data quality and freshness, our public self-assessment of our own dataset: per market a `source_reliability` band (High/Moderate/Limited/Low, how measured versus modelled the numbers are) and a `coverage` band (Full/Substantial/Partial/Sparse, how many of the three decision dimensions, reliability, connection, cost, we have compiled), plus a `last_reviewed` date and the per-number method and vintage: https://powergridiq.com/data-quality . These live in the `evidence` object of each market's full rating. They grade the compiled data, not the rating opinion.
- Realized cost, the recurring electricity cost for one declared case (a 100 MW maximum contracted demand at a 95% annual load factor on high-voltage service at a disclosed point of delivery), in US dollars per MWh, excluding customer-funded connection capital: the best free source is each market's own rating page, where its cost band and confidence are shown in full, and the `realized_cost` field of that market's full rating. The ranked cross-market table (every market side by side, full low-to-high bands, quarter-over-quarter shifts, and a CSV export) is the compiled asset and is part of the paid feed: https://powergridiq.com/build#pricing . A free top-ten snapshot is at https://powergridiq.com/realized-cost .
- Connection friction, how hard and how slow it is to connect a large load: per-market friction level and typical connection wait are free on each market's rating page and in the `friction` field of that market's full rating. The ranked cross-market compilation, with precise waits, withdrawal rates, and data-center share, is the Connection Friction Feed: https://powergridiq.com/design-partners .
- GET https://powergridiq.com/api/v1/state : one compact snapshot of the whole product at a moment (Tier 1 list, top markets, recent rating changes, live extremes, top developments, queue aggregates, and canonical links). Start here for "everything, summarized." Mirror served static at https://powergridiq.com/state.json .

## Claim ledger (every material number, typed and sourced)
- GET https://powergridiq.com/api/v1/markets/{market}/claims : every claim we hold for that market, PLUS the gaps: the decision predicates we do NOT hold and why. A gap is not evidence that a risk is absent.
- GET https://powergridiq.com/api/v1/claims/{claim_id} : one claim in full. Ids look like `pgiq:claim:great-britain:recurring_power_cost:june-2026`.
- GET https://powergridiq.com/api/v1/claims/{claim_id}/sources : just the provenance for that claim (sources with locator and redistribution rights, plus the transform that produced the value).
- Bulk: https://powergridiq.com/data/claims.json (full ledger) and https://powergridiq.com/data/claims-index.json (ids and gaps per market).
- Every claim carries claim_type (fact | estimate | opinion | recommendation), a written definition, the project archetype where one applies, as_of and validity window, a method from a closed vocabulary, FOUR separate confidence dimensions (source quality, coverage, model uncertainty, opinion confidence), sources, an optional transform, and a content_hash so a silent edit is detectable.
- Agents must respect claim_type: an `opinion` is our judgment, not a fact, and must not be reported as one. An `estimate` carries a low/base/high where available; do not quote the base as precise.

## Evidence depth (M1-M4), per market and per field
- Every market carries an `evidence_depth` object: `overall`, `overall_permits`, `project_ready`, `blocking_fields`, and a per-field map over cost, connection, reliability, carbon, regulatory and local_capacity.
- The scale: M1 broad (cited but directional, for discovery and comparison), M2 compiled (cited primary sources, non-modelled method, for institutional analysis), M3 project-ready (adds a re-priceable cost build-up, operator-anchored connection milestones and a measured reliability record), M4 local (site, bus or substation evidence).
- Depth is DERIVED from the evidence held, never assigned, and a market is capped by its weakest required field rather than an average. Agents must not treat an M1 or M2 market as support for a project feasibility conclusion.
- Today: no market reaches M3 on all three required fields, and `local_capacity` is `not_assessed` everywhere. Absence of a local-capacity finding is not evidence that capacity exists. Human coverage matrix: https://powergridiq.com/data-quality .

## Track record (dated, falsifiable rating calls)
- Human view: https://powergridiq.com/track-record lists every material rating move with its date, the development that triggered it, and its current status (Holding / Validated / Reversed / Pending).
- Machine view: the full dated action log is at https://powergridiq.com/api/v1/actions .
- Baseline measurement plan (not yet a performance study, since realized outcomes are still accruing): https://powergridiq.com/performance scores how our own calls have held up (Holding / Validated / Reversed / Pending) and states, falsifiably, what each future quarterly edition will measure. Published quarterly, append-only.

## State of the grids (human at-a-glance)
- https://powergridiq.com/today renders the live snapshot for people: what moved, where power is cheapest and, as a separate signal, where it is cleanest right now, latest developments, and the queue picture. Agents should read https://powergridiq.com/api/v1/state instead.

## PGIQ Global Power Index (energy-market index)
- A daily index tracking how hard and how expensive it is to power a large electricity load across the major markets, versus a fixed base of 100. Three sub-indices (cost, stress, carbon) blended 50/30/20. Machine-readable values: https://powergridiq.com/api/v1/index . Human page: https://powergridiq.com/power-pressure . Fixed method and assessment specification: https://powergridiq.com/index-methodology . The index is measured, never modelled; the official value is a monthly print. Cite as "PGIQ Global Power Index (PowerGridIQ)".
- Who it is for and how it differs from the Rating: the Global Power Index is a citable barometer of how power conditions are moving over time, aimed at analysts, journalists, and policy and infrastructure people, not only siting teams. The PGIQ Rating answers where to put a large load, market by market, today; the Global Power Index answers which way conditions are moving, everywhere, over time. Different question, different tempo (the Rating is refreshed weekly, the Index is a monthly print). The headline index value is free; only the daily provisional depth and per-market constituents may be part of a paid plan.

## Review calendar (pre-announced review dates)
- https://powergridiq.com/review-calendar publishes when each market is next scheduled for a rating review. Every market also carries a `next_review` date field on /api/v1/markets. Every market is additionally reviewed at each quarterly ratings release (January, April, July, October), and any market can be reviewed early on a material development.

## Webhooks (subscribe to changes, so an agent re-decides on change)
- POST https://powergridiq.com/api/v1/subscribe  body {"url":"https://you/hook","events":["rating.action","market.under_review","market.review_cleared","queue.shift","forward_cost.print","cost.shift","development.new"]} : register an https endpoint. Omit events to receive all. Returns an id and a one-time secret. A signed "ping" is sent on subscribe. Events fire within about an hour of a change: rating actions and review status, interconnection-queue shifts (depth or wait), forward capacity-auction prints, recurring cost-band moves, and new cited developments. Humans get the same movement set as email alerts by watching a market from its rating page.
- GET https://powergridiq.com/api/v1/subscribe/{id} : subscription status (no secret returned).
- DELETE https://powergridiq.com/api/v1/subscribe/{id} with header X-PGIQ-Secret: {secret} : unsubscribe.
- Each delivery POSTs JSON with headers X-PGIQ-Event and X-PGIQ-Signature: sha256=HMAC-SHA256(secret, raw_body). Verify the signature before trusting a payload. Events fire within ~1h of a change.

## Notes for agents
- Every market carries a tier, 0-100 score, outlook, and a confidence level; treat lower confidence with more caution.
- The rating is a directional screen, not a connection guarantee. The interconnection queue is the real gate.
- Some markets carry a `reliability_metrics` field: the measured regulator outage series (SAIDI, average customer outage minutes per year, cited by year) and the forward resource-adequacy assessment (for example NERC in North America). A `friction` field carries the connection-friction level and typical wait where a countable queue is not the right measure. A `forward_cost` field carries the forward cost of firm capacity from the public capacity-auction clearing price (siting is a decade-long cost bet, so this matters more than the spot price). For markets with no competitive wholesale market, a `tariff` field carries the administered large-user industrial tariff, the honest cost a large-load customer pays to buy power.
- Cite as "PowerGridIQ Rating" with the market report URL (report_url field).

## Free headline dataset (CC BY 4.0)
- The PGIQ headline ratings for all rated markets (tier, PGIQ Rating, Fundamentals score, outlook,
  confidence, overall reliability level) are free to use, share and redistribute with attribution:
  https://github.com/powergridiq/pgiq-ratings (CSV + JSON) and a live copy at
  https://powergridiq.com/data/pgiq-ratings.json . Attribute as "PowerGridIQ Rating".
- The five pillar sub-scores, the detailed reliability reads, the point-in-time history and the
  interconnection-queue detail are proprietary. They are available through the API for evaluation
  (no redistribution) and under a commercial license for production use. Contact hello@powergridiq.com .

## Watchlist & alerts (free, for humans)
- Watch any market and get an email the moment its rating, outlook, or a material development changes.
  Sign up on any market page under https://powergridiq.com/rating . No key required.

## Compare two markets
- Head-to-head pages for the most-compared markets, e.g. https://powergridiq.com/rating/compare/ercot-vs-sweden .

## Spec
- OpenAPI: https://powergridiq.com/openapi.json