A shipping report needs more than a fuel price. Keep the grade, port, currency, unit and assessment date with every observation. Otherwise a difference between two numbers can reflect mismatched data instead of a useful comparison.
Start with the Singapore–Rotterdam VLSFO reporting workflow. It provides a concrete example using two port-specific series and a downloadable CSV reporting script.
Keep grade and port separate
VLSFO, MGO and HFO are different fuel categories. A report comparing the same grade across ports answers a different question from one comparing two grades at the same port. Label that distinction before calculating a spread.
The worked workflow uses VLSFO_SGSIN_USD for Singapore and VLSFO_NLRTM_USD for Rotterdam, both expressed in USD per metric tonne. It does not demonstrate an HFO–VLSFO grade spread or establish access to every marine fuel series.
sbb-itb-a92d0a3
Do not mistake collection time for assessment time
The time your system receives a record and the date represented by its price are separate facts. Preserve both where available. A newly collected record may still contain an earlier assessment.
For a daily port comparison, require matching UTC assessment dates and compatible grade, currency and unit. If a source supplies only a record timestamp, do not silently promote it to an assessment timestamp. Mark the missing information and withhold a comparison that depends on it.
| Check | Acceptable comparison | Failure response |
|---|---|---|
| Grade | Both observations identify VLSFO | Keep different-grade observations separate. |
| Currency and unit | Both use USD per metric tonne | Withhold the raw difference until any conversion is explicit. |
| Assessment date | Both represent the same UTC date | Display individual dated values without a matched spread. |
| Validity | Prices are present, valid and within the freshness policy | Show unavailable or stale status instead of zero. |
| Source status | Records pass the workflow’s quality checks | Do not disguise synthetic or flagged records as usable observations. |
Calculate and label the port difference
The workflow calculates Singapore minus Rotterdam. A positive result means the Singapore observation is higher for that matched comparison; a negative result means it is lower. Include the sign convention and assessment date in the report so a reader can reproduce the calculation.
This benchmark difference excludes freight, delivery, vessel and commercial terms. It is not a supplier quotation, a procurement recommendation or guaranteed savings. Compare current delivered offers and voyage assumptions separately before making an operational decision.
Build the first report
- Open the VLSFO comparison workflow and review the required series.
- Follow the download and setup instructions for its reporting example.
- Keep the API key in an environment variable and confirm dataset access.
- Run the marine report and inspect its individual observations, dates and comparison status.
- Save the CSV and source records before importing them into a spreadsheet or dashboard.
When validation fails, preserve enough information to explain the failure. An HTTP success alone is insufficient: the content can still be missing, stale or mismatched. Handle authentication, access and rate-limit failures visibly, and keep any last successful report clearly dated.
Expand only after the first comparison works
For additional ports or grades, confirm the exact symbols, units, source timing, account permissions and historical coverage in the OilPriceAPI documentation. Do not infer those capabilities from the existence of one latest-price series.
To produce the first dated output, build the VLSFO report and check dataset access.