98 lines
3.2 KiB
Markdown
98 lines
3.2 KiB
Markdown
# EIA Brent Price Source — Primary with FRED Fallback
|
|
|
|
**Date:** 2026-04-14
|
|
**Status:** Approved
|
|
|
|
## Problem
|
|
|
|
FRED (`DCOILBRENTEU`) publishes Brent crude prices with a lag on top of the EIA's own publication delay. As of 2026-04-14, FRED's most recent data is 2026-04-02 — 12 days stale. EIA is the original data source; FRED mirrors it. Using EIA directly removes the mirroring lag.
|
|
|
|
## Goal
|
|
|
|
Replace FRED as the primary source for `fetchBrentPrices()` with the EIA Open Data API, keeping FRED as a fallback so the system degrades gracefully if EIA is unavailable.
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
All changes are confined to `app/Services/OilPriceService.php` and supporting config/env files.
|
|
|
|
### `fetchBrentPrices()` — updated flow
|
|
|
|
```
|
|
1. $rows = fetchFromEia()
|
|
2. if ($rows === null):
|
|
Log::warning('OilPriceService: EIA fetch failed, falling back to FRED')
|
|
$rows = fetchFromFred()
|
|
3. if ($rows === null):
|
|
Log::error('OilPriceService: both EIA and FRED fetch failed')
|
|
return
|
|
4. BrentPrice::upsert($rows, ['date'], ['price_usd'])
|
|
```
|
|
|
|
### `fetchFromEia(): ?array` (new private method)
|
|
|
|
- Endpoint: `GET https://api.eia.gov/v2/petroleum/pri/spt/data/`
|
|
- Params: `api_key`, `frequency=daily`, `data[0]=value`, `facets[series][]=RBRTE`, `sort[0][column]=period`, `sort[0][direction]=desc`, `length=30`
|
|
- Returns `null` on: HTTP error, exception, empty/missing `response.data` array
|
|
- Maps each row: `['date' => $row['period'], 'price_usd' => (float) $row['value']]`
|
|
- Filters rows where `value` is `'.'` (EIA uses same placeholder as FRED)
|
|
|
|
### `fetchFromFred(): ?array` (extracted private method)
|
|
|
|
- Existing FRED logic moved verbatim from the current `fetchBrentPrices()` body
|
|
- Returns `null` on: HTTP error, exception, empty observations
|
|
- Maps each row: `['date' => $obs['date'], 'price_usd' => (float) $obs['value']]`
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### `config/services.php`
|
|
|
|
Add under existing entries:
|
|
```php
|
|
'eia' => [
|
|
'api_key' => env('EIA_API_KEY'),
|
|
],
|
|
```
|
|
|
|
### `.env.example`
|
|
|
|
Add:
|
|
```
|
|
EIA_API_KEY= # US EIA Open Data API key — register free at eia.gov/opendata
|
|
```
|
|
|
|
FRED key stays in `.env.example` (still used as fallback).
|
|
|
|
---
|
|
|
|
## Logging
|
|
|
|
| Event | Level | Message |
|
|
|---|---|---|
|
|
| EIA fetch succeeded | — | (no log — normal path) |
|
|
| EIA fetch failed, FRED used | `warning` | `OilPriceService: EIA fetch failed, falling back to FRED` |
|
|
| Both failed | `error` | `OilPriceService: both EIA and FRED fetch failed` |
|
|
| No rows after filter | `warning` | `OilPriceService: no valid EIA observations returned` (existing pattern) |
|
|
|
|
---
|
|
|
|
## Tests
|
|
|
|
Existing `OilPriceService` fetch tests are updated (not replaced):
|
|
|
|
1. **EIA succeeds** — `Http::fake()` returns valid EIA response; assert upsert called with correct rows; assert FRED endpoint never called.
|
|
2. **EIA fails, FRED succeeds** — EIA returns 500; assert FRED endpoint called; assert upsert called with FRED rows; assert warning logged.
|
|
3. **Both fail** — both return 500; assert upsert never called; assert error logged.
|
|
4. **EIA returns empty data** — `response.data` is `[]`; assert falls back to FRED.
|
|
|
|
---
|
|
|
|
## Out of Scope
|
|
|
|
- No changes to `generatePrediction()`, `PredictOilPrices` command, or scheduler
|
|
- No new service classes or interfaces
|
|
- No changes to `brent_prices` schema
|