# Catalogue

The following guide describes how to access the catalogue in Sparta's API

The `/catalogue` endpoint provides structured metadata for all datasets available in the Sparta platform. Each item in the response represents a single curve quotation, offering users a powerful way to discover data relevant to their needs. API Reference: <https://documentation.sparta.app/v2.0/docs/sparta-catalogue>.

> 📘 Example
> 
> **GET** `/catalogue?filter[region]=NWE&filter[quotation]=Margin price by load&filter[vertical]=ULSD&pageSize=1`
> 
> ```json JSON Response
> 
>     "items": [
>         {
>             "id": "0007f4dd-673a-5309-b606-178aadbd2d2c",
>             "name": "RAS LAFFAN - BARCELONA VIACAPE Jet-A1 LR2 - Margin by Load",
>             "units": "$/mt",
>             "filters": {
>                 "region": "AG",
>                 "vessel": "LR2",
>                 "loadPort": "RAS LAFFAN",
>                 "vertical": "Jet",
>                 "productType": "Physical",
>                 "dischargePort": "BARCELONA",
>                 "quotation": "Margin by load"
>             },
>             "properties": {
>                 "vessel": "LR2",
>                 "routing": "VIACAPE",
>                 "specName": "Jet-A1",
>                 "incoterms": "EXS",
>                 "routeCode": "LAFBCNVIACAPELR2",
>                 "loadPortName": "RAS LAFFAN",
>                 "loadPortRegion": "AG",
>                 "dischargePortName": "BARCELONA",
>                 "dischargePortRegion": "MED"
>             },
>             "contracts": [
>                 "11-15 Aug 25",
>                 "11-15 Nov 25",
>                 "11-15 Jul 25",
>                 "16-20 Oct 25",
>                 ...
>             ]
>         }
>     ],
>     "self": "https://api.sparta.app/v2/catalogue?page=1&pageSize=1",
>     "next": "https://api.sparta.app/v2/catalogue?page=2&pageSize=1",
>     "prev": null,
>     "last": "https://api.sparta.app/v2/catalogue?page=4221&pageSize=1"
> }
> ```

# 🔍 Filtering the catalogue

The curve quotations may include their own custom filters like `grade`or `loadPort`. 

There are filters that apply to every curver quotation to refine search results from the beginning:

- vertical
- quotation
- region

## Quotations by vertical

| Gasoline                | ULSD                    | Jet                     | Naphtha                 | Crude                      | Fuel Oil |
| :---------------------- | :---------------------- | :---------------------- | :---------------------- | :------------------------- | :------- |
| Ara Ref Margin by load  | Delivered price by load | Delivered price by load | Delivered price by load | Delivered Outright Price   | Blend    |
| Blender Margin by load  | Fob                     | Fob                     | Fob                     | Delivered price by load    | Margin   |
| Delivered price by load | Freight Costs           | Freight Costs           | Freight Costs           | Fob                        | Price    |
| Freight Costs           | Freight Rate            | Freight Rate            | Freight Rate            | Freight Costs              | Sales    |
| Freight Rate            | Margin by load          | Margin by load          | Margin by load          | Freight Rate               |          |
| Price                   | Sales                   | Sales                   | Sales                   | GPW Complex Setup          |          |
| Sales                   |                         |                         |                         | GPW Medium Setup           |          |
|                         |                         |                         |                         | GPW Simple Setup           |          |
|                         |                         |                         |                         | Ref Margin Complex by load |          |
|                         |                         |                         |                         | Ref Margin Medium by load  |          |
|                         |                         |                         |                         | Ref Margin simple by load  |          |

## Regions by vertical

| Gasoline | ULSD            | Jet             | Naphtha | Crude     | Fuel Oil |
| :------- | :-------------- | :-------------- | :------ | :-------- | :------- |
| AG       | AG              | AG              | AG      | AG        | ARA      |
| ARA      | FAR EAST        | FAR EAST        | Med     | LATAM     | FUJ      |
| HOU      | Med             | RED SEA         | NWE     | NORTH SEA | MED      |
| HOU Bld  | RED SEA         | SOUTH EAST ASIA | USGC    | WAF       | SING     |
| HOU Ref  | SOUTH EAST ASIA | USGC            | WAF     | WCMEX     | USGC     |
| SING     | USGC            | WCI             |         |           |          |
|          | WAF             |                 |         |           |          |
|          | WCI             |                 |         |           |          |

# :spiral_notepad: Curve quotation information

| Field      | Description                                            |
| :--------- | :----------------------------------------------------- |
| id         | Unique identifier of the curve quotation.              |
| name       | Name of the curve quotation.                           |
| quotation  | Name of the quotation type.                            |
| units      | Units of the curve quotation.                          |
| filters    | Filterable dimensions specific to the curve quotation. |
| properties | Any additional metadata.                               |
| contracts  | List of available contracts for curve quotation.       |

# 📆 Contracts

Each curve quotation lists the contract periods for which data is available. Contracts are represented like:

| Monthly Contracts | 5-Day Rolling Windows | Quarterly Contracts |
| :---------------- | :-------------------- | :------------------ |
| ...               | ..                    | ..                  |
| ...               | ...                   | ...                 |
| May 25            | 1-5 Jun 25            | Q1 25               |
| Jun 25            | 6-10 Jun 25           | Q2 25               |
| Jul 25            | 11-15 Jun 25          | Q3 25               |
| Aug 25            | 16-20 Jun 25          | Q4 25               |
| Sep 25            | 21-25 Jun 25          | Q1 26               |
| Oct 25            | 26-EOM Jun 25         | Q2 26               |
| ...               | ...                   | ...                 |