Marine Fuel (VLSFO/HFO) Price Data for Shipping Applications

If you track marine fuel with one price, your shipping math is off. After IMO 2020 cut sulfur from 3.5% to 0.5%, fleets split across VLSFO, MGO, HFO380, and HFO180, and each grade can price differently by port.

Here’s the short version: I need to track each fuel grade as its own code, use port-level spot prices, and store source timestamps with every record. That’s what lets me check bunker quotes, estimate voyage fuel cost, and measure scrubber payback with fewer gaps.

What matters most:

• VLSFO and MGO are not the same fuel and should not share one label
• HFO380 and HFO180 should stay separate because viscosity and engine use differ
• Port matters: Singapore, Rotterdam, Fujairah, and Houston can show different prices on the same day
• The Hi-5 spread = VLSFO minus HFO380, a key input for scrubber payback
• Store prices in $/MT, with fields like code, price, currency, unit, timestamp, port_code, and source
• Use API data for math, and keep formatted values for display only

A simple way to think about it: grade tells me what fuel I’m pricing, port tells me where, and timestamp tells me when. If one of those is missing, the number can mislead.

Item	What I track	Why it matters
Fuel grade	VLSFO, MGO, HFO380, HFO180	Cost, compliance, and engine use differ
Port	SGSIN, Rotterdam, Fujairah, Houston, etc.	Local bunker prices do not match across ports
Time	Source assessment timestamp	An unchanged price may still be current
Spread	VLSFO-HFO380, VLSFO-MGO	Scrubber ROI, ECA routing, fuel-switch checks

My takeaway: this article shows how to model marine fuel price data in a clean way and pull live port-grade prices with OilPriceAPI for shipping dashboards, voyage tools, internal portals, and bunker workflows.

Marine fuel grades developers need to model

VLSFO and MGO in compliant operations

VLSFO is the main IMO 2020-compliant residual fuel. MGO is a lighter distillate fuel used in ECAs, port operations, auxiliary engines, and emergency generators.

These two fuels shouldn't sit under the same label. MGO is much less viscous than VLSFO, so storage, heating, and fuel-switching logic work differently. If you're building a model, treat them as separate grades from the start.

HFO380 and HFO180 in scrubber-enabled fleets

Ships with scrubbers can burn HFO380 and HFO180. Keep those separate in the model too, because viscosity affects engine fit and heating needs.

HFO380 can reach up to 380 cSt at 50°C. HFO180 is the lower-viscosity option, which makes it a better fit for older engines or engines with tighter viscosity limits. If you group both under a generic HFO bucket, you miss those day-to-day operating differences.

Store each grade as its own symbol so port-level analytics stay in sync. After that, you can track port-level spot prices and the spreads between grades without muddying the data.

Why grade spreads belong in your data model

In many cases, the spread is the number people care about most.

The VLSFO vs. HFO380 spread - often called the "Hi-5" spread - is a main input for scrubber ROI analysis. The VLSFO vs. MGO spread helps with ECA routing and fuel-switching logic because it shows the cost of moving from residual fuel to distillate fuel in controlled areas.

Separate historical series also help with:

• Route economics
• Quote validation
• Port-by-port price analysis

Check the record timestamp before treating an unchanged price as stale, especially when monitoring shifts in the global oil market.

sbb-itb-a92d0a3

Why port-level spot prices matter in shipping applications

Once you model fuel grades separately, the next step is where those prices are assessed.

Port-level spot prices show local buying conditions that shape procurement, routing, and margin analysis. Local supply, refinery output, and logistics can shift from one port to another, so one assessment alone isn't enough for voyage economics or bunker buying.

How differences between ports affect voyage economics

Fuel prices at major bunkering hubs like Singapore, Rotterdam, Fujairah, and Houston don't move in sync. Shipping systems need port-level values so teams can compare bunker options across ports instead of leaning on one regional number for an entire route.

That’s why operators run port spread checks before picking a bunker port. They compare VLSFO, MGO, and HFO380 prices across likely ports to guide procurement and voyage planning. Without port-level data, that comparison is still just an estimate.

How spot prices support bunkering, routing, and margin analysis

Port-level data feeds several day-to-day workflows at the same time. Operations teams use it to estimate bunker costs at the place of purchase, check supplier quotes, and reconcile bunker invoices against market moves.

When you pair spot prices with vessel ETAs, consumption curves, and route schedules, those workflows get tighter. For scrubber-equipped fleets, tracking the VLSFO vs. HFO380 spread at the specific port of call is key when calculating the payback period of exhaust gas cleaning systems.

Check the timestamp before you treat an unchanged assessment as stale.

Benchmark data vs. port-level bunker data: a comparison

Both data types have a place in a well-built shipping system. Here’s where each one fits.

Data Scope	Best Use Case	Limitations	Shipping-System Impact
Global/Regional Benchmark	Macro-level trend analysis and market sentiment	Misses local logistics, barge fees, and port-specific supply context	Adds context but cannot support precise voyage budgeting
Port-Level Spot Price	Bunker procurement, voyage estimation, and supplier quote validation	Coverage may be limited to major bunkering hubs	Improves operational accuracy, margin protection, and fuel cost optimization

Use benchmark data for context and trend visibility. But build procurement and voyage tools on port-level spot prices where coverage is available. Storing both, along with source timestamps, gives your system room to support both operational and analytical use cases from the same data layer.

Use port-level prices in a record structure that keeps grade, port, timestamp, and source separate. That gives your pricing layer the input it needs before you map fields and call the API using JSON or XML.

How to structure and integrate marine fuel price data with OilPriceAPI

Core fields for marine fuel records

With grade, port, and spread logic set, the next step is a clean record schema.

Use one simple schema for each marine fuel price record. Each record should include a commodity code, the numeric price, the unit of measurement, the currency, a source timestamp, a port code, and a data source.

Field	Data Type	Description	Example Value
code	String	Identifier for grade, port, and currency	VLSFO_SGSIN_USD
price	Float	Numeric spot price	676.00
unit	String	Unit of measurement	MT
currency	String	Currency of the price	USD
timestamp	String (ISO 8601)	Time of market assessment	2026-07-13T01:19:00Z
port_code	String	Port code	SGSIN
source	String	Data source	market_reporting

Store price as a numeric float in USD/MT so spread calculations like VLSFO minus HFO380 work directly. Use the source timestamp for time-series logic, and keep ingestion fields like created_at or updated_at only for system tracking. When modeling grade spreads, pull both records from the same timestamp or business day so the economics line up.

Calling the latest prices endpoint

Once the record shape is set, map it to the latest-prices request.

GET https://api.oilpriceapi.com/v1/prices/latest
Authorization: Token YOUR_API_KEY

Use the by_code parameter to retrieve a specific port-grade code. The response includes a status field and a data object with price, formatted, code, currency, unit, and timestamp. Use price for calculations. Use formatted only for UI display.

Marine fuel benchmarks usually update on business days, based on upstream bunker assessment schedules. So it makes sense to ingest on the source update cycle and use timestamp to spot stale data.

For the full list of supported symbols, filters, and response fields, see the OilPriceAPI documentation.

Integration options: Excel, Google Sheets, Python, and Node.js

The same payload can feed spreadsheets, data pipelines, and dashboards. The best setup depends on who uses it and how often it needs to refresh.

Environment	Typical Shipping Use	Refresh Pattern	Integration Notes
Excel	Voyage estimation and bunker procurement reports	Manual or workbook refresh	Use the dedicated OilPrice add-in for refreshable formulas.
Google Sheets	Shared fuel surcharge and margin tools	On-open or timed trigger via Apps Script	Store the API key in Script Properties for custom functions.
Python	Voyage optimization, margin analysis, historical modeling	Scheduled cron or ingestion script	Use the requests library for backend pipelines and analytics workflows.
Node.js	Real-time maritime dashboards and internal portals	Event-driven or API-to-API calls	Use axios or node-fetch for server-side integration.

Each environment has a dedicated walkthrough: Python tutorial, Node.js tutorial, Excel guide, and Google Sheets guide.

In dashboards and reports, show timestamp next to price so users can see when the market value was last assessed.

Conclusion: Building better shipping tools with marine fuel price data

Treat VLSFO, MGO, HFO380, and HFO180 as separate codes. That keeps compliance checks, scrubber usage, and bunker economics accurate.

Port-level spot prices add the local bunker view that broad benchmarks miss. And that local view shapes bunkering, routing, and margin analysis in a very direct way. Once you have that port-level layer, the next step is simple: automate ingestion through the API.

API pulls handle updates for you and keep each record timestamped at the source.

Key takeaways for developers and analysts

In practice, that comes down to four things:

• Use consistent grade symbols. Keep VLSFO, MGO, HFO380, and HFO180 the same across every port and data source so spread calculations and compliance checks stay aligned.
• Preserve port-level context. Query port-specific codes because voyage economics depend on the lift port, not just the grade.
• Use timestamp and source to separate fresh data from stale data.
• Embed live and historical data into your tools. Dashboards, internal portals, and fuel lookup workflows work better when price data flows in automatically instead of being updated by hand.

Start with one port-specific code, then expand coverage. Check our API integration FAQ for setup details. Get a free API key at oilpriceapi.com.

FAQs

How should I code fuel grades by port?

Use commodity codes that combine the fuel grade, port, and currency. Since IMO 2020, port-level spot prices matter for bunker cost tracking, supplier quote benchmarking, and route economics.

Request the latest price with GET /v1/prices/latest and by_code. For example, use VLSFO_SGSIN_USD or VLSFO_NLRTM_USD.

Then check the returned timestamp and metadata to confirm the benchmark is current.

How often should marine fuel prices refresh?

Marine fuel benchmarks, including VLSFO, MGO, HFO380, and HFO180, update on business days based on upstream bunker assessment schedules. On weekends and public holidays, the latest data may still show the prior business day.

So instead of relying on a fixed refresh interval, check the timestamp in each API response. If a price hasn’t changed, the timestamp tells you whether the data is current or simply the latest available.

Why do timestamps matter for bunker pricing?

Timestamps help developers check whether bunker price data is current and still fit for jobs like invoice reconciliation and internal benchmarking.

That matters because bunker assessments don't update on weekends or public holidays. So if a price hasn't changed, that may be perfectly normal. Looking at the timestamp alongside the source field helps you tell the difference between stale data and a market that's simply holding steady.