Supply & Demand

Note

available on platforms : Platform.Liquids

class kpler.sdk.resources.supply_demand.SupplyDemand(configuration, column_ids=True, log_level=None)

The SupplyDemand endpoint returns supply and demand metrics data values aggregated or split by country for a given product/ zone/ time period/selected snapshot, It also allows listing the available products and snapshots for the main endpoint

get(product=None, metrics=None, split=None, zones=None, start_date=None, end_date=None, snapshot_date=None)

Parameters

• product – Optional[str] Name of product to retrieve data for

• metrics – Optional[List[Enum]] SupplyDemandMetric Returns only provided metrics

• split – Optional[Enum] SupplyDemandSplit Choose whether returned data are aggregated or split by country

• zones – Optional[List[str]] Names of countries/geographical zones

• start_date – Optional[date] Start of the period (YYYY-MM-DD), must be after 2017-01-01

• end_date – Optional[date] End of the period (YYYY-MM-DD), maximum of 18 month from today

• snapshot_date – Optional[date] Date of the snapshot to retrieve data from (YYYY-MM-DD)

Examples

>>> from datetime import date
... from kpler.sdk.resources.supply_demand import SupplyDemand
... from kpler.sdk import SupplyDemandSplit, SupplyDemandMetric
... sd_client = SupplyDemand(config)
... sd_client.get(
...     product="Crude/Co",
...     metrics=[SupplyDemandMetric.Supply, SupplyDemandMetric.Demand],
...     start_date=date(2020,10,1),
...     end_date=date(2020,11,1),
...     zones=["Japan"],
...     split=SupplyDemandSplit.Total
... )

Snapshot Date	Date	Product	Metric	Zones	Value	Unit
2022-09-15	2020-10-01	Crude/Co	Supply (kbd)	Japan	3	kbd
2022-09-15	2020-10-01	Crude/Co	Demand (kbd)	Japan	2279	kbd
2022-09-15	2020-10-01	Crude/Co	Supply (kbd)	Japan	3	kbd
2022-09-15	2020-10-01	Crude/Co	Demand (kbd)	Japan	2504	kbd

get_products()

Args: None .. rubric:: Examples

>>> from datetime import date
... from kpler.sdk.resources.supply_demand import SupplyDemand
... sd_client = SupplyDemand(config)
... sd_client.get_products()

Product	metrics	Snapshot Start Date	Snapshot End Date
Crude/Co	supply,demand,refineryRun,directCrudeUse,balance,netExport,stockChange,balancingFactor	2022-08-15	2022-09-15

get_snapshots(product=None, start_date=None, end_date=None)

Parameters

• product – Optional[str] Name of product to retrieve snapshots for

• start_date – Optional[date] Start of the period (YYYY-MM-DD)

• end_date – Optional[date] End of the period (YYYY-MM-DD)

Examples

>>> from datetime import date
... from kpler.sdk.resources.supply_demand import SupplyDemand
... sd_client = SupplyDemand(config)
... sd_client.get_snapshots(
...     product="Crude/Co",
...     start_date=date(2022,08,1),
...     end_date=date(2022,10,1),
... )

Date	Product
2022-08-14	Crude/Co
2022-09-01	Crude/Co

get_us_balances(product=None, metrics=None, start_date=None, end_date=None, granularity=None)

Parameters

• product – Optional[Enum] Name of product to retrieve data for

• metrics – Optional[List[Enum]] SupplyDemandMetric Returns only provided metrics

• start_date – Optional[date] Start of the period (YYYY-MM-DD), must be after 2017-01-01

• end_date – Optional[date] End of the period (YYYY-MM-DD), maximum of 12 month from today

• granularity – Optional[Enum] SupplyDemandUsBalancesGranularity Choose the granularity of the data

Examples

>>> from datetime import date
... from kpler.sdk.resources.supply_demand import SupplyDemand, SupplyDemandUsBalancesMetric
... from kpler.sdk import SupplyDemandUsBalancesGranularity, SupplyDemandUsBalancesProduct
... sd_client = SupplyDemand(config)
... sd_client.get_us_balances(
...     product=SupplyDemandUsBalancesProduct.Crude,
...     metrics=[SupplyDemandUsBalancesMetric.crude.NetImport],
...     start_date=date(2020,1,1),
...     end_date=date(2020,6,1),
...     granularity=SupplyDemandUsBalancesGranularity.Weekly

Snapshot Date	Date	Product	Metric	Zones	Value	Unit
2024-03-28	2023-01-01	Crude/Co	netImport	United States	3243	kbd
2024-03-28	2023-02-01	Crude/Co	netImport	United States	2657	kbd
2024-03-28	2023-03-01	Crude/Co	netImport	United States	2261	kbd

class kpler.sdk.SupplyDemandMetric(value)

Balance = 'balance'

BalancingFactor = 'balancingFactor'

Demand = 'demand'

DirectCrudeUse = 'directCrudeUse'

NetExport = 'netExport'

RefineryRun = 'refineryRun'

StockChange = 'stockChange'

Supply = 'supply'

class kpler.sdk.SupplyDemandSplit(value)

Country = 'country'

Total = 'total'