{"openapi":"3.1.0","info":{"title":"Grid Shopper Electricity Market API","version":"1.0.0","description":"Public electricity market data for utility territories, including territory summaries, current offers, and recent rate history."},"servers":[{"url":"https://gridshopper.com"}],"externalDocs":{"description":"Developer documentation","url":"https://gridshopper.com/developers"},"tags":[{"name":"Utilities","description":"Utility territory directory and snapshots"},{"name":"Offers","description":"Current supplier offers for a utility territory"},{"name":"History","description":"Recent lowest-offer history for a utility territory"}],"paths":{"/api/v1/utilities":{"get":{"tags":["Utilities"],"summary":"List tracked utility territories","description":"Returns the utility territories Grid Shopper tracks, including the Grid Shopper landing page and official rateboard URL when available.","responses":{"200":{"description":"Tracked utility territories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UtilityDirectoryResponse"},"examples":{"default":{"value":{"documentation_url":"https://gridshopper.com/developers","utilities":[{"id":"pa/peco","name":"PECO","state":"Pennsylvania","state_abbr":"PA","url":"https://gridshopper.com/pa/peco","rateboard_url":"https://www.papowerswitch.com/"}]}}}}}}}}},"/api/v1/utilities/{state}/{utility}":{"get":{"tags":["Utilities"],"summary":"Get a utility territory summary","parameters":[{"name":"state","in":"path","required":true,"schema":{"type":"string"},"description":"State slug, for example `pa` or `oh`."},{"name":"utility","in":"path","required":true,"schema":{"type":"string"},"description":"Utility slug, for example `peco` or `aep`."}],"responses":{"200":{"description":"Utility territory summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UtilitySummaryResponse"},"examples":{"default":{"value":{"id":"pa/peco","name":"PECO","state":"Pennsylvania","state_abbr":"PA","updated_at":"2026-03-08T19:11:33.109Z","utility_rate":0.11024,"nopec_rate":null,"market":{"supplier_count":42,"offer_count":132,"avg_12month_rate":0.1367,"avg_rate_change_1d":null,"avg_rate_change_7d":0.11},"lowest_offer":{"supplier":"Inspire Clean Energy","term_months":3,"rate":0.0899,"rate_change_1d":null,"rate_change_7d":-0.3},"source":"Pennsylvania rateboard","url":"https://gridshopper.com/pa/peco","sources":{"territory_page_url":"https://gridshopper.com/pa/peco","rateboard_url":"https://www.papowerswitch.com/","methodology_url":"https://gridshopper.com/methodology/data-sources","documentation_url":"https://gridshopper.com/developers"}}}}}}},"404":{"description":"Unknown utility territory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/utilities/{state}/{utility}/offers":{"get":{"tags":["Offers"],"summary":"Get current supplier offers for a utility territory","parameters":[{"name":"state","in":"path","required":true,"schema":{"type":"string"}},{"name":"utility","in":"path","required":true,"schema":{"type":"string"}},{"name":"max_term","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Optional maximum contract term in months."},{"name":"supplier","in":"query","required":false,"schema":{"type":"string"},"description":"Optional case-insensitive supplier-name filter."}],"responses":{"200":{"description":"Current supplier offers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffersResponse"},"examples":{"default":{"value":{"id":"pa/peco","utility_rate":0.11024,"updated_at":"2026-03-08T19:11:33.109Z","offer_count":2,"url":"https://gridshopper.com/pa/peco","sources":{"territory_page_url":"https://gridshopper.com/pa/peco","rateboard_url":"https://www.papowerswitch.com/","methodology_url":"https://gridshopper.com/methodology/data-sources","documentation_url":"https://gridshopper.com/developers"},"offers":[{"supplier":"Inspire Clean Energy","term_months":3,"rate":0.0899,"source_url":"https://www.example.com/offer.pdf"}]}}}}}},"404":{"description":"Unknown utility territory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/utilities/{state}/{utility}/history":{"get":{"tags":["History"],"summary":"Get recent lowest-offer history for a utility territory","parameters":[{"name":"state","in":"path","required":true,"schema":{"type":"string"}},{"name":"utility","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":180,"default":30},"description":"Number of recent daily rows to return."}],"responses":{"200":{"description":"Recent daily lowest-offer history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryResponse"},"examples":{"default":{"value":{"id":"pa/peco","updated_at":"2026-03-08T19:11:33.109Z","url":"https://gridshopper.com/pa/peco","sources":{"territory_page_url":"https://gridshopper.com/pa/peco","rateboard_url":"https://www.papowerswitch.com/","methodology_url":"https://gridshopper.com/methodology/data-sources","documentation_url":"https://gridshopper.com/developers"},"history":[{"date":"2026-03-08","lowest_rate":0.0899,"lowest_supplier":"Inspire Clean Energy","lowest_term_months":3,"avg_12month_rate":0.1367,"min_12month_rate":0.0899,"max_12month_rate":0.1499}]}}}}}},"404":{"description":"Unknown utility territory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error","available"],"properties":{"error":{"type":"string","example":"Utility not found"},"available":{"type":"string","example":"/api/v1/utilities"}}},"UtilitySources":{"type":"object","required":["territory_page_url","rateboard_url","methodology_url","documentation_url"],"properties":{"territory_page_url":{"type":"string","format":"uri"},"rateboard_url":{"type":["string","null"],"format":"uri"},"methodology_url":{"type":"string","format":"uri"},"documentation_url":{"type":"string","format":"uri"}}},"UtilityDirectoryItem":{"type":"object","required":["id","name","state","state_abbr","url","rateboard_url"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"state":{"type":"string"},"state_abbr":{"type":"string"},"url":{"type":"string","format":"uri"},"rateboard_url":{"type":["string","null"],"format":"uri"}}},"UtilityDirectoryResponse":{"type":"object","required":["documentation_url","utilities"],"properties":{"documentation_url":{"type":"string","format":"uri"},"utilities":{"type":"array","items":{"$ref":"#/components/schemas/UtilityDirectoryItem"}}}},"UtilityMarketSummary":{"type":"object","required":["supplier_count","offer_count","avg_12month_rate","avg_rate_change_1d","avg_rate_change_7d"],"properties":{"supplier_count":{"type":"integer"},"offer_count":{"type":"integer"},"avg_12month_rate":{"type":"number"},"avg_rate_change_1d":{"type":["number","null"]},"avg_rate_change_7d":{"type":["number","null"]}}},"LowestOffer":{"type":"object","required":["supplier","term_months","rate","rate_change_1d","rate_change_7d"],"properties":{"supplier":{"type":"string"},"term_months":{"type":"integer"},"rate":{"type":"number"},"rate_change_1d":{"type":["number","null"]},"rate_change_7d":{"type":["number","null"]}}},"UtilitySummaryResponse":{"type":"object","required":["id","name","state","state_abbr","updated_at","utility_rate","nopec_rate","market","lowest_offer","source","url","sources"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"state":{"type":"string"},"state_abbr":{"type":"string"},"updated_at":{"type":["string","null"],"format":"date-time"},"utility_rate":{"type":["number","null"]},"nopec_rate":{"type":["number","null"]},"market":{"$ref":"#/components/schemas/UtilityMarketSummary"},"lowest_offer":{"$ref":"#/components/schemas/LowestOffer"},"source":{"type":"string"},"url":{"type":"string","format":"uri"},"sources":{"$ref":"#/components/schemas/UtilitySources"}}},"Offer":{"type":"object","required":["supplier","term_months","rate","source_url"],"properties":{"supplier":{"type":"string"},"term_months":{"type":"integer"},"rate":{"type":"number"},"source_url":{"type":["string","null"],"format":"uri"}}},"OffersResponse":{"type":"object","required":["id","utility_rate","updated_at","offer_count","url","sources","offers"],"properties":{"id":{"type":"string"},"utility_rate":{"type":["number","null"]},"updated_at":{"type":["string","null"],"format":"date-time"},"offer_count":{"type":"integer"},"url":{"type":"string","format":"uri"},"sources":{"$ref":"#/components/schemas/UtilitySources"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}}}},"HistoryRow":{"type":"object","required":["date","lowest_rate","lowest_supplier","lowest_term_months","avg_12month_rate","min_12month_rate","max_12month_rate"],"properties":{"date":{"type":"string","format":"date"},"lowest_rate":{"type":["number","null"]},"lowest_supplier":{"type":"string"},"lowest_term_months":{"type":["number","null"]},"avg_12month_rate":{"type":["number","null"]},"min_12month_rate":{"type":["number","null"]},"max_12month_rate":{"type":["number","null"]}}},"HistoryResponse":{"type":"object","required":["id","updated_at","url","sources","history"],"properties":{"id":{"type":"string"},"updated_at":{"type":["string","null"],"format":"date-time"},"url":{"type":"string","format":"uri"},"sources":{"$ref":"#/components/schemas/UtilitySources"},"history":{"type":"array","items":{"$ref":"#/components/schemas/HistoryRow"}}}}}},"x-gridshopper":{"methodology_url":"https://gridshopper.com/methodology/data-sources","documentation_url":"https://gridshopper.com/developers","llms_url":"https://gridshopper.com/llms.txt"}}