Oil Price API Marine Fuels API

openapi: 3.2.0
info:
  title: Oil Price API V1 Marine Fuels API
  version: v1
  description: 'Source-aware oil and energy data API. Check each endpoint''s source timestamp,

    coverage, and freshness fields before using a response in a time-sensitive workflow. ## Authentication


    API-key endpoints use `Authorization: Token YOUR_API_KEY`. Operations that do

    not require an API key explicitly declare an empty security requirement. `/v1/demo/prices` is keyless. ## Rate Limiting


    - Free tier: 50 requests per day

    - Paid tiers have plan-specific monthly quotas. - `402` means the allowance is exhausted: a Free or post-trial caller

    must upgrade, and a paid plan has used its monthly allowance (the body

    carries `MONTHLY_QUOTA_EXCEEDED` and reset metadata, so do not retry before

    the reset). `429` means an active-trial allowance or a rolling rate limit

    (for example the hourly safety limit) is exceeded; retry `429` and transient

    `5xx` responses with bounded backoff. - Website login and signup (`POST /sessions` and `POST /users`) also enforce

    authentication-attempt limits independently of API plan quotas: 3 attempts

    per normalized email address in 5 minutes, and 3 attempts per minute per

    verified visitor IP. Requests without a verified proxy identity retain

    the existing 20 requests/minute IP ceiling. A `429` on these routes means

    wait for `Retry-After` before retrying; upgrading a plan does not remove

    authentication-attempt limits. Futures curves are never refused because a market is closed or a session has

    just reopened. The last available data is served with `metadata.freshness_status`,

    `metadata.stale`, `metadata.latest_data_at` and `metadata.stale_by_minutes`:

    `outside_market_hours` while the venue is closed (weekend, daily break,

    holiday); `awaiting_first_print` for the first 30 minutes of a new session

    while only a valid prior close exists; `degraded` when the market is open and

    the source is behind. None of these is a fresh trade; source timestamps remain

    unchanged. Data older than the 96-hour serving bound is refused with 503. Gasoil reports `metadata.freshness_status: no_recent_trades` when the

    benchmark contract has not traded within 30 minutes but our collector confirmed

    the quote within that window and the curve printed within 90 minutes. The last

    trade is served with its true `latest_data_at` and `stale_by_minutes`, plus

    `source_checked_at` and `curve_latest_trade_at`. Paid monthly-cap responses include `retry_guidance`: immediate retries cannot

    restore quota. When a representative sample supports it, `batching_opportunity`

    describes an estimated lower request rate; batching does not restore an already

    exhausted allowance. It may replace an unnecessary upgrade recommendation. ## Continuous futures coverage


    On `/v1/futures/continuous/brent`, `/v1/futures/continuous/wti` and their

    `/historical` routes, `metadata.history_available_from` is the earliest

    stored public continuous futures source date, falling back to collection

    date for older imports without a source timestamp. It is a date string or

    null when no public observations exist. Coverage metadata is cached for up

    to one hour and does not promise observations or volume on every later date. It describes the archive independently of the request''s date range; account

    depth limits remain in `metadata.history_window` on historical responses. Latest-response `metadata.total_historical_records` counts stored public

    snapshots, including revisions, rather than distinct source dates. Latest

    quotes and their prior-day comparisons exclude private organization rows

    and other price types. Repeated source timestamps select the later collected

    revision; the oldest metadata/response cache formats are no longer used. ## Spread and indicator query parameters


    Spread and indicator endpoints reject unrecognized query parameter names with

    HTTP 400 and `error.code: UNKNOWN_PARAMETERS`, after authentication and access

    checks. The error includes `unrecognized_parameters`, `allowed_parameters`,

    and a `suggestions` map for recognized date-name mistakes; values are not

    echoed.'
  contact:
    name: Oil Price API Support
    email: support@oilpriceapi.com
    url: https://oilpriceapi.com
  license:
    name: Commercial License
    url: https://oilpriceapi.com/terms
servers:
- url: https://api.oilpriceapi.com
  description: Production server
tags:
- name: Marine Fuels
  description: Marine and bunker fuel prices.
paths:
  /v1/prices/marine-fuels:
    get:
      summary: Get marine fuel prices for all ports
      operationId: getV1PricesMarineFuels
      tags:
      - Marine Fuels
      description: 'Global marine bunker fuel prices including VLSFO, HFO 380, and MGO.

        Covers major bunkering ports worldwide.

        **Premium Feature** - Professional tier and above.'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Marine fuel prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarineFuelsResponse'
        '401':
          description: Unauthorized
        '403':
          description: Premium access required
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/prices/marine-fuels/latest:
    get:
      summary: Get latest marine fuel prices by port
      operationId: getV1PricesMarineFuelsLatest
      description: Retrieve the latest available marine fuel prices for one or more supported ports.
      tags:
      - Marine Fuels
      parameters:
      - name: port_code
        in: query
        required: false
        description: UN/LOCODE from the marine ports endpoint (for example SGSIN or NLRTM); port is an alias for port_code.
        schema:
          type: string
          example: SGSIN
      - name: fuel_type
        in: query
        required: false
        description: Marine grade (VLSFO, HFO_380, HFO_180, MGO_05S, MGO_01S) or full marine series code; comma-separated lists are accepted. Unknown entries return 400.
        schema:
          type: string
          example: VLSFO
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Latest marine fuel prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarineFuelLatestResponse'
        '400':
          description: Invalid marine fuel filter or missing required parameters
        '401':
          description: Unauthorized
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/prices/marine-fuels/historical:
    get:
      summary: Get historical marine fuel prices
      operationId: getV1PricesMarineFuelsHistorical
      description: Retrieve the latest collection of each marine-fuel assessment, newest first. The response keeps distinct sources, currencies and price types separate. Undated rows retain their collection time. Up to 1,000 observations are returned after deduplication; metadata.truncated indicates omitted matches. metadata.period describes returned as_of values, while requested_period records the query window. Neither a successful response nor truncated=false promises complete daily coverage. Results are cached for 30 minutes.
      tags:
      - Marine Fuels
      parameters:
      - name: port_code
        in: query
        required: true
        description: Port code
        schema:
          type: string
          example: SGSIN
      - name: fuel_type
        in: query
        required: true
        description: Marine grade (VLSFO, HFO_380, HFO_180, MGO_05S, MGO_01S) or full marine series code; comma-separated lists are accepted. Unknown entries return 400.
        schema:
          type: string
          example: VLSFO_SGSIN_USD
      - name: days
        in: query
        required: false
        description: Rolling history window in days
        schema:
          type: integer
          minimum: 1
          maximum: 365
          default: 30
          example: 365
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Historical marine fuel data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarineFuelHistoricalResponse'
        '400':
          description: Invalid marine fuel filter or missing required parameters
        '401':
          description: Unauthorized
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/marine-ports:
    get:
      summary: Get all marine fuel ports
      operationId: getV1MarinePorts
      tags:
      - Marine Fuels
      description: 'Retrieve all available marine fuel ports with their details and capabilities.

        Returns port information including coordinates, fuel services, and trading hours.'
      parameters:
      - name: region
        in: query
        required: false
        description: Filter ports by geographic region
        schema:
          type: string
          enum:
          - Asia
          - Europe
          - Americas
          - Middle East
          example: Asia
      - name: country
        in: query
        required: false
        description: Filter ports by country name
        schema:
          type: string
          example: Singapore
      - name: major_ports
        in: query
        required: false
        description: Return only major bunkering hubs
        schema:
          type: boolean
          default: false
          example: true
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: List of marine fuel ports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarinePortsResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/marine-ports/{port_code}:
    get:
      summary: Get specific marine fuel port with prices
      operationId: getV1MarinePortsByPortCode
      tags:
      - Marine Fuels
      description: 'Retrieve detailed information about a specific marine fuel port including

        current bunker prices for all available fuel grades.'
      parameters:
      - name: port_code
        in: path
        required: true
        description: Port identifier code
        schema:
          type: string
          enum:
          - SGSIN
          - NLRTM
          - USHOU
          - AEFUJ
          - HKHKG
          - USLAX
          - USNYC
          - BRSSZ
          example: SGSIN
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Port details with current prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarinePortDetailResponse'
        '404':
          description: Port not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    RateLimitErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: RATE_LIMIT_EXCEEDED
            message:
              type: string
              example: Rate limit exceeded
            details:
              type: object
              properties:
                limit:
                  type: integer
                  example: 100
                remaining:
                  type: integer
                  example: 0
                reset_at:
                  type: string
                  format: date-time
                  example: '2025-01-20T11:00:00.000Z'
                retry_after:
                  type: integer
                  example: 3600
            documentation_url:
              type: string
              example: https://docs.oilpriceapi.com/rate-limits
    MarineFuelsResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          type: array
          items:
            type: object
            properties:
              port_code:
                type: string
                example: SINGAPORE
              port_name:
                type: string
                example: Singapore
              prices:
                type: object
                properties:
                  VLSFO:
                    type: number
                    example: 685
                  HFO_380:
                    type: number
                    example: 545
                  MGO:
                    type: number
                    example: 875
              currency:
                type: string
                example: USD
              unit:
                type: string
                example: per MT
              updated_at:
                type: string
                format: date-time
    MarineFuelPrice:
      type: object
      properties:
        fuel_type:
          type: string
          example: MGO_05S
          description: Fuel grade code
        fuel_name:
          type: string
          example: Marine Gas Oil 0.5%S
          description: Full fuel name
        price:
          type: number
          format: float
          example: 682.5
          description: Price in USD per metric ton
        formatted:
          type: string
          example: $682.50
          description: Formatted price string
        currency:
          type: string
          example: USD
          description: Price currency
        unit:
          type: string
          example: metric_ton
          description: Price unit
        source:
          type: string
          example: market_reporting
          description: Data source
        timestamp:
          type: string
          format: date-time
          example: '2025-08-05T00:32:05.928Z'
          description: Price update timestamp
    MarinePortDetailResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          properties:
            port:
              $ref: '#/components/schemas/MarinePortWithPrices'
    MarinePort:
      type: object
      properties:
        code:
          type: string
          example: SGSIN
          description: Unique port identifier
        name:
          type: string
          example: Singapore
          description: Port name
        country:
          type: string
          example: Singapore
          description: Country where port is located
        region:
          type: string
          example: Asia
          description: Geographic region
        major_port:
          type: boolean
          example: true
          description: Whether this is a major bunkering hub
        coordinates:
          type: object
          properties:
            latitude:
              type: number
              format: float
              example: 1.2966
            longitude:
              type: number
              format: float
              example: 103.7764
        fuel_services:
          type: array
          items:
            type: string
          example:
          - MGO_05S
          - VLSFO
          - HFO_380
          - HFO_180
          description: Available fuel types at this port
        trading_hours:
          type: string
          example: 24/7
          description: Port operating hours
    MarineFuelHistoricalResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          properties:
            prices:
              type: array
              items:
                type: object
                properties:
                  port_code:
                    type: string
                  fuels:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        price:
                          type: number
                        as_of:
                          type: string
                          format: date-time
                        timestamp:
                          type: string
                          format: date-time
            metadata:
              type: object
              properties:
                count:
                  type: integer
                  description: Number of returned fuel observations
                port_count:
                  type: integer
                  description: Number of returned port groups
                limit:
                  type: integer
                  example: 1000
                truncated:
                  type: boolean
                  description: True when additional matching observations exceeded the limit
                period:
                  $ref: '#/components/schemas/MarineFuelHistoryPeriod'
                requested_period:
                  $ref: '#/components/schemas/MarineFuelHistoryPeriod'
    MarinePortsResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          properties:
            ports:
              type: array
              items:
                $ref: '#/components/schemas/MarinePort'
            count:
              type: integer
              example: 8
            filters:
              type: object
              properties:
                region:
                  type:
                  - string
                  - 'null'
                country:
                  type:
                  - string
                  - 'null'
                major_ports_only:
                  type: boolean
    MarineFuelHistoryPeriod:
      type: object
      properties:
        start:
          type:
          - string
          - 'null'
          format: date-time
        end:
          type:
          - string
          - 'null'
          format: date-time
    MarineFuelLatestResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          properties:
            port_code:
              type: string
              example: SINGAPORE
            fuel_type:
              type: string
              example: VLSFO
            price:
              type: number
              example: 685
            currency:
              type: string
              example: USD
            unit:
              type: string
              example: per MT
            week_change:
              type: number
              example: 15
            month_change:
              type: number
              example: -25
            updated_at:
              type: string
              format: date-time
    MarinePortWithPrices:
      allOf:
      - $ref: '#/components/schemas/MarinePort'
      - type: object
        properties:
          metadata:
            type: object
            properties:
              timezone:
                type: string
                example: Asia/Singapore
              annual_volume_mt:
                type: integer
                example: 50000000
                description: Annual bunkering volume in metric tons
          recent_prices:
            type: array
            items:
              $ref: '#/components/schemas/MarineFuelPrice'
          statistics:
            type: object
            properties:
              total_fuel_types:
                type: integer
                example: 4
              recent_price_updates:
                type: integer
                example: 10
              last_update:
                type: string
                format: date-time
                example: '2025-08-05T00:32:10Z'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code (e.g. UNAUTHORIZED, NOT_FOUND, INVALID_PARAMETER).
              example: UNAUTHORIZED
            message:
              type: string
              example: 'Missing or invalid API key. Include header: Authorization: Token YOUR_API_KEY'
            status:
              type: integer
              example: 401
            request_id:
              type: string
              example: fa0e389f-ca86-47b2-b167-2b4645a2fb8b
            docs:
              type: string
              example: https://docs.oilpriceapi.com#UNAUTHORIZED
            signup_url:
              type:
              - string
              - 'null'
              example: https://www.oilpriceapi.com/auth/signup
            demo_endpoint:
              type:
              - string
              - 'null'
              example: /v1/demo/prices
  responses:
    InternalServerError:
      description: Unexpected server error. Retry transient failures with bounded backoff and retain the request ID when contacting support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key as: Authorization: Token YOUR_API_KEY'
externalDocs:
  description: OilPriceAPI developer documentation
  url: https://docs.oilpriceapi.com