balance
Get a country's monthly petroleum balance for one product - production, trade, stocks, and refinery activity, one column per flow of the JODI questionnaire.
Examples
from openbb import obb
# Get the United States crude oil balance - one column per questionnaire flow.
obb.jodi.oil.balance(provider='jodi')
# Get India's gasoline balance, in thousand metric tons.
obb.jodi.oil.balance(provider='jodi', country='india', product='gasoline', unit='ktons', start_date='2020-01-01')
Parameters
- standard
- jodi
country: str | None
Default: united_states
The country to get data for, by name or ISO 3166-1 alpha-2 code.
product: str | None
Default: crude_oil
Description
The petroleum product to get the balance for. The first four are primary products, the rest are secondary products. JODI questionnaire definitions:
crude_oil: Crude oil, including lease condensate and excluding NGL.
ngl: Liquid or liquefied hydrocarbons recovered from gas separation plants and gas processing facilities.
other_crude: Refinery feedstocks, additives/oxygenates, and other hydrocarbons.
total_crude: The sum of the primary categories: crude oil + NGL + other.
lpg: Liquefied petroleum gases, comprising propane and butane.
naphtha: Naphtha used as feedstock for producing high octane gasoline and as feedstock for the chemical/petrochemical industries.
gasoline: Motor gasoline and aviation gasoline; motor gasoline includes biogasoline, e.g. ethanol blends.
kerosene: Kerosenes, comprising jet kerosene and other kerosene.
jet_fuel: Kerosene type jet fuel: aviation fuel used for aviation turbine power units; a subset of the amount reported under kerosenes.
gas_diesel_oil: Gas/diesel oil, for automotive and other purposes; biodiesel is included.
fuel_oil: Heavy residual oil/boiler oil, including bunker oil.
other_products: Refinery gas, ethane, petroleum coke, lubricants, white spirit and SBP, bitumen, paraffin waxes, and other petroleum products.
total_products: The sum of all secondary product categories; demand for total products includes direct use of crude oil, NGL, and other hydrocarbons.
Choices
- crude_oil
- ngl
- other_crude
- total_crude
- lpg
- naphtha
- gasoline
- kerosene
- jet_fuel
- gas_diesel_oil
- fuel_oil
- other_products
- total_products
unit: str | None
Default: kbd
The unit of measurement. kbd: thousand barrels per day; kbbl: thousand barrels; kl: thousand kilolitres; ktons: thousand metric tons; conversion_factor: barrels per thousand metric tons.
Choices
- kbd
- kbbl
- kl
- ktons
- conversion_factor
start_date: date | None | str
Start date of the data, in YYYY-MM-DD format. Defaults to the first data period, 2002-01-01.
end_date: date | None | str
End date of the data, in YYYY-MM-DD format.
use_cache: bool | None
Default: True
If True, the source tables are cached under the user cache directory and revalidated against the source at most once per day, downloading again only when JODI has published an update.
Returns
results: JodiOilBalance
Serializable results.
provider: str | None
Provider name.
warnings: Optional[list[Warning_]]
List of warnings.
chart: Optional[Chart]
Chart object.
extra: dict[str, Any]
Extra info.
Data
- standard
- jodi
date: date | str
The date of the data.
production: float | None
Production (primary products). Marketed production, after removal of impurities but including quantities consumed by the producer in the production process.
refinery_output: float | None
Refinery output (secondary products). Gross refinery output of finished products, including refinery fuel.
from_other_sources: float | None
From other sources (primary products). Inputs of additives, biofuels, and other hydrocarbons produced from non-oil sources such as coal, natural gas, and renewable energy.
receipts: float | None
Receipts (secondary products). Primary product receipts (quantities of oil used directly without processing in a refinery) plus recycled products. Receipts for other oil products include direct use of crude oil and NGL.
imports: float | None
Imports. Goods having physically crossed the international boundaries, excluding transit trade and international marine and aviation bunkers.
exports: float | None
Exports. Goods having physically crossed the international boundaries, excluding transit trade and international marine and aviation bunkers.
products_transferred: float | None
Products transferred. For primary products, the sum of products transferred and backflows from the petrochemical industry; for secondary products, imported petroleum products reclassified as feedstocks for further processing in the refinery, without delivery to final consumers.
interproduct_transfers: float | None
Interproduct transfers (secondary products). Reclassification of products because their specification has changed or because they are blended into another product; a negative entry indicates a product to be reclassified, a positive entry a reclassified product. Interproduct transfers for other oil products include interproduct transfers of crude oil and NGL.
direct_use: float | None
Direct use (primary products). Crude oil, NGL, and other hydrocarbons used directly without being processed in oil refineries, for example crude oil burned for electricity generation.
stock_change: float | None
Stock change. Closing minus opening stock level; a positive number corresponds to a stock build, a negative number to a stock draw.
statistical_difference: float | None
Statistical difference. Differences between observed supply flows and refinery intake or demand.
refinery_intake: float | None
Refinery intake (primary products). Observed refinery throughputs.
demand: float | None
Demand (secondary products). Deliveries or sales to the inland market (domestic consumption) plus refinery fuel plus international marine and aviation bunkers. Demand for other oil products includes direct use of crude oil, NGL, and other primary hydrocarbons.
closing_stocks: float | None
Closing stocks. The primary stock level at the end of the month within national territories; includes stocks held by importers, refiners, stock-holding organisations, and governments.