Skip to main content

Example Queries

This section provides practical examples of common queries and use cases to help you get started. These examples demonstrate different ways to interact with the system and can serve as templates for your own queries.

You can copy/paste any of these example queries into the /GraphQL UI endpoint. The GraphQL UI provides an interactive environment where you can see all available types, queries, and fields in our GraphQL schema.

Below you'll find queries for:

Retrieving All Spot Prices​

The following query fetches all available spot prices for all available ports and fuel grades:

query allSpotPrices {
  latestSpotPrices {
    port {
      id
      name
      countryName
      portRank
    }
    fuelGrade {
      id
      description
    }
    latestPrices {
      publishedDate
      price
    }
  }
}

This query returns:

  • Port information (ID and name)
    • ID (the port's unique identifier)
    • Name (the port's name)
    • CountryName (the port's country name)
    • PortRank (pseudo-rank from 1 to 7, where 1 are major ports and 7 includes all ports)
  • Fuel grade details (ID and description)
    • ID (the fuel grade's unique identifier)
    • Description (the fuel grade's description)
  • Latest price data including:
    • The published date of the price indication
    • The price indication

The response will include all available spot prices, organized by port and fuel grade, with their corresponding dates and values.

Filtering Spot Prices By Fuel Grades​

The following query demonstrates how to fetch spot prices for all available ports for specific fuel grades:

query allSpotPricesByFuelGrade {
  latestSpotPrices(input: { fuelGradeIds: ["MGO", "VLSFO"] }) {
    port {
      id
      name
      countryName
      portRank
    }
    fuelGrade {
      id
      description
    }
    latestPrices {
      publishedDate
      price
    }
  }
}

Currently supported fuel grade IDs are:

  • MGO - Marine Gas Oil
  • VLSFO - Very Low Sulphur Fuel Oil
  • HSFO - High Sulphur Fuel Oil
  • LNG - Liquefied Natural Gas
  • BIOFUEL - Bio Fuel

The response will include spot prices only for the specified fuel grades (MGO and VLSFO), making it more focused and efficient than querying all fuel grades.

Filtering Spot Prices By Ports​

The following query demonstrates how to fetch spot prices for all fuel grades at specific ports:

query allSpotPricesByPort {
  latestSpotPrices(input: { portIds: ["SGSIN", "NLRTM", "AEFJR"] }) {
    port {
      id
      name
    }
    fuelGrade {
      id
      description
    }
    latestPrices {
      publishedDate
      price
    }
  }
}

This query shows how to:

  • Filter results for specific ports only
  • Get all available fuel grades at selected locations
  • Focus on key bunkering hubs

The example filters for three major ports:

  • Singapore (SGSIN)
  • Rotterdam (NLRTM)
  • Fujairah (AEFJR)

For a complete list of available ports and their details, including time zones and rankings, see the Retrieving Port Information section below.

Use this query when you need to:

  • Monitor all fuel prices in specific regions
  • Compare different fuel options at major ports
  • Analyze regional price variations
  • Create port-specific market reports
  • Track availability of fuels at key locations

The response will include spot prices for all available fuel grades at the specified ports, allowing for comprehensive analysis of specific locations.

Filtering Spot Prices By Fuel Grades And Ports​

The following query demonstrates how to fetch spot prices for specific fuel grades at selected ports:

query spotPricesByFuelGradeAndPort {
  latestSpotPrices(
    input: {
      fuelGradeIds: ["MGO", "VLSFO"]
      portIds: ["SGSIN", "NLRTM", "AEFJR"]
    }
  ) {
    port {
      id
      name
      countryName
      portRank
    }
    fuelGrade {
      id
      description
    }
    latestPrices {
      publishedDate
      price
    }
  }
}

This query shows how to:

  • Combine multiple filter criteria
  • Filter by both fuel grades and specific ports
  • Target precise market segments

The example filters for:

  • Fuel grades: MGO and VLSFO
  • Ports: Singapore (SGSIN), Rotterdam (NLRTM), and Fujairah (AEFJR)

Use this query when you need to:

  • Monitor specific trade routes
  • Compare prices in key bunkering hubs
  • Create regional market analysis
  • Track price spreads between major ports
  • Generate focused reports for specific markets

The response will include only the spot prices that match both the specified fuel grades and ports, providing the most targeted and efficient data retrieval.

Retrieving Fixed Forward Prices​

All of the queries shown above for spot prices can be used for fixed forward prices by simply replacing latestSpotPrices with latestFixedForwardPrices. Here are some examples:

Retrieving All Fixed Forward Prices​

query allFixedForwardPrices {
  latestFixedForwardPrices {
    port {
      id
      name
      countryName
      portRank
    }
    fuelGrade {
      id
      description
    }
    latestPrices {
      publishedDate
      price
      effectiveDate
      relativeDate {
        count
        unit
      }
    }
  }
}

Filtering Fixed Forward Prices By Fuel Grades And Ports​

query fixedForwardPricesByFuelGradesAndPorts {
  latestFixedForwardPrices(
    input: {
      fuelGradeIds: ["MGO", "VLSFO"]
      portIds: ["SGSIN", "NLRTM", "AEFJR"]
    }
  ) {
    port {
      id
      name
      countryName
      portRank
    }
    fuelGrade {
      id
      description
    }
    latestPrices {
      publishedDate
      price
      effectiveDate
      relativeDate {
        count
        unit
      }
    }
  }
}

The response structure and filtering capabilities are identical to those described in the spot prices sections above. Fixed forward prices include additional date-related fields:

  • effectiveDate: The date when the fixed forward price becomes effective
  • relativeDate: The time span from the current date, expressed in months (ranging from 0 to 24 months)

Additional Useful Query Fields​

When querying prices, there are several additional fields you might find useful that weren't shown in the examples above:

Retrieving Prices With Unit Conversions​

The following query demonstrates how to fetch spot prices with automatic unit conversions for LNG:

query spotPricesWithUnitConversions {
  latestSpotPrices(input: { fuelGradeIds: ["LNG"] }) {
    port {
      id
      name
      countryName
      portRank
    }
    fuelGrade {
      id
      description
    }
    latestPrices {
      publishedDate
      price
      conversions {
        MMBtu
        MWh
        GJ
        M3
        barrel
        gallon
      }
    }
  }
}

This query shows how to:

  • Filter results for a specific fuel grade (LNG)
  • Request automatic unit conversions to different energy and volume units
  • Get prices in multiple units simultaneously

The response includes:

  • Port and fuel grade information
  • Base price in the default unit (USD/MT)
  • Converted values in:
    • MMBtu - Million British Thermal Units
    • MWh - Megawatt Hours
    • GJ - Gigajoules
    • M3 - Cubic Meters
    • barrel - Barrels
    • gallon - Gallons

Not all conversions are available for every fuel grade — fields will be null when a conversion does not apply.

This is particularly useful when you need to:

  • Compare fuel prices across different unit standards
  • Display prices in multiple units for different markets
  • Perform energy cost comparisons across fuel types

Emission Data for Fuel Grades​

You can extend any query that returns fuel grade information to include emission data:

fuelGrade {
  id
  description
  emission
  emissionFactor
}

This is particularly useful for:

  • Environmental reporting
  • Emissions calculations
  • Compliance monitoring

Port Location Details​

When querying port information, you can include geographical and time zone data:

port {
  id
  name
  coordinates {
    latitude
    longitude
  }
  timeZone {
    name
    offset
  }
}

This additional information can help with:

  • Route planning and optimization
  • Local time calculations
  • Geographical analysis
  • Regional reporting

You can include these fields in any of the queries shown in the previous sections by adding them to the respective port or fuelGrade selections.

Algorithm Information​

When querying prices, you can include information about the algorithm used for price calculations:

latestPrices {
  publishedDate
  price
  algorithmInformation {
    name
    version
  }
}

The algorithm name indicates how the price was determined:

  • Aggregated: Direct price aggregation from sufficient datapoints at the specific port
  • Modeled: Price estimation using data models for ports with lower transaction volumes
  • Calculated: Price calculation based on data from nearby ports when local data is insufficient

This information is useful for:

  • Understanding the methodology behind price calculations
  • Tracking algorithm updates and changes
  • Audit and compliance purposes
  • Data provenance tracking

You can include this field in any of the price queries shown in the previous sections.

Using Version Parameters​

The API supports multiple versions of price data, allowing you to access both stable and experimental pricing information. You can specify the version using the version parameter in your queries.

Version Options​

  • STABLE (default): Production-ready price data with full coverage
  • EXPERIMENTAL: Experimental or beta pricing algorithms which are subject to change.

Note: When no version is specified, the API defaults to STABLE.

Retrieving Experimental Spot Prices​

query experimentalSpotPrices {
  latestSpotPrices(input: { version: EXPERIMENTAL }) {
    port {
      id
      name
      countryName
      portRank
    }
    fuelGrade {
      id
      description
    }
    latestPrices {
      publishedDate
      price
    }
  }
}

Retrieving Experimental Fixed Forward Prices​

query experimentalFixedForwardPrices {
  latestFixedForwardPrices(input: { version: EXPERIMENTAL }) {
    port {
      id
      name
      countryName
      portRank
    }
    fuelGrade {
      id
      description
    }
    latestPrices {
      publishedDate
      price
      effectiveDate
      relativeDate {
        count
        unit
      }
    }
  }
}

Combining Version with Other Filters​

You can combine the version parameter with other filters like fuel grades and ports:

query experimentalPricesWithFilters {
  latestSpotPrices(
    input: {
      version: EXPERIMENTAL
      fuelGradeIds: ["MGO", "VLSFO"]
      portIds: ["SGSIN", "NLRTM"]
    }
  ) {
    port {
      id
      name
      countryName
      portRank
    }
    fuelGrade {
      id
      description
    }
    latestPrices {
      publishedDate
      price
    }
  }
}

Retrieving Port Information​

The following query demonstrates how to fetch information about ports, including pagination and filtering capabilities:

query ports {
  ports(first: 10, filter: { portRank: 3 }) {
    totalCount
    pageInfo {
      startCursor
      hasPreviousPage
      hasNextPage
      endCursor
    }
    edges {
      cursor
      node {
        id
        name
        country
        portRank
        timeZone {
          name
          offset
        }
      }
    }
  }
}

This query shows how to:

  • Retrieve port details with pagination (first 10 results)
  • Filter ports by rank (portRank: pseudo-rank from 1 to 7, where 1 are major ports and 7 includes all ports)
  • Get essential port information including:
    • Port ID and name
    • Country location
    • Port ranking
    • Time zone details

The response includes:

  • Total count of matching ports
  • Pagination information for navigating results
  • Port details for each matching location
  • Time zone information including name and UTC offset

To retrieve the next page of results when hasNextPage is true, use the endCursor from the previous query in the after parameter:

query ports {
  ports(first: 10, after: "grpir", filter: { portRank: 3 }) {
    totalCount
    pageInfo {
      startCursor
      hasPreviousPage
      hasNextPage
      endCursor
    }
    edges {
      cursor
      node {
        id
        name
        country
        portRank
        timeZone {
          name
          offset
        }
      }
    }
  }
}

This pagination system allows you to:

  • Navigate through large sets of results in manageable chunks
  • Use the after parameter with the previous query's endCursor to fetch the next page
  • Keep track of your position in the result set using pageInfo
  • Maintain consistent page sizes across requests

The cursor-based pagination ensures stable and efficient navigation through the port data, especially when dealing with large datasets or frequent updates.