vortexasdk.endpoints.eia_forecasts

Try me out in your browser:

Binder

EIAForecasts

EIAForecasts(self)

EIA forecasts Endpoint, use this to search through Vortexa's EIA Forecasts data.

The data includes:

  • date: date of the forecast
  • forecast_fri: Vortexa's data science based forecast of the EIA number to be published on the week
  • value: Actual EIA import/export numbers as published by the EIA Weekly Supply Estimates report
  • stocks: EIA stocks (kbl)
  • cover: Cover (days of Supply for the whole of the US, as published by the EIA Weekly Supply Estimates report)
  • runs: refinery runs (refiner “Percent Operable Utilization” as published by the EIA Weekly Supply Estimates report)

search

EIAForecasts.search(
  preset: str = 'padd1-gasoline-imports',
  filter_time_min: datetime = datetime.datetime(2020, 1, 1, 0, 0),
  filter_time_max: datetime = datetime.datetime(2020, 1, 31, 0, 0))

Find EIA forecasts for a given preset and date range.

Arguments

  • preset: Use to specify what geography and product information you would like to query.

  • Preset can be: 'padd1-gasoline-imports', 'padd3-gasoline-imports', 'padd5-gasoline-imports', 'us-gasoline-exports', 'padd1-crude-imports', 'padd3-crude-imports', 'padd5-crude-imports', 'us-crude-exports', 'padd1-diesel-imports', 'padd3-diesel-imports', 'padd5-diesel-imports', 'us-diesel-exports', 'padd1-jet-imports', 'padd5-jet-imports', 'us-jet-exports', 'padd1-fueloil-imports', 'padd3-fueloil-imports', 'padd5-fueloil-imports' or 'us-fueloil-exports'

    filter_time_min: The UTC start date of the time filter

    filter_time_max: The UTC end date of the time filter

Returns

List of EIA Forecast object matching selected 'preset'.

Examples

Find PADD5 gasoline imports EIA forecasts from January 2019.

>>> from datetime import datetime
>>> from vortexasdk import EIAForecasts
>>> df = EIAForecasts().search(
...     preset="padd5-gasoline-imports",
...     filter_time_min=datetime(2020, 1, 1),
...     filter_time_max=datetime(2020, 1, 31)
... ).to_df()

returns

date forecast_fri value stocks cover runs
2020-01-31T00:00:00.000Z 454.96048964485 323 9541 26.5 65.9
2020-01-24T00:00:00.000Z 545.453497230504 579 10461 25.9 61.5
2020-01-17T00:00:00.000Z 510.289752707662 549 10325 25.2 64.7
2020-01-10T00:00:00.000Z 469.841470826967
2020-01-03T00:00:00.000Z 640.443229654771

Some values can be NULL: value, stocks, cover, runs. It can happen when:

  • it's a very recent forecast, the Vortexa's data science based forecast (forecast_fri) is available but the complete EIA data isn't yet
  • it's an older forecast and the data is not available

vortexasdk.endpoints.eia_forecasts_result

EIAForecastResult

EIAForecastResult(*, records: typing.List,
                  reference: typing.Dict[str, typing.Any])

Container class that holds the result obtained from calling the EIAForecasts endpoint.

model_config

to_list

EIAForecastResult.to_list()

Represent EIAForecast data as a list.

to_df

EIAForecastResult.to_df(
    columns:
    typing.Union[typing_extensions.Literal['all'], typing.List[str], NoneType] = ['date', 'forecast_fri', 'value', 'stocks', 'cover', 'runs']
)

Represent EIA forecasts as a pd.DataFrame.

Arguments

  • columns: The EIA forecasts columns we want in the dataframe. Enter columns='all' to include all columns. Defaults to columns = ['date', 'forecast_fri', 'value', 'stocks', 'cover', 'runs'].

Returns

pd.DataFrame of EIA forecasts.