vortexa-claude-skills 1.0.0

package/context/reference-endpoints.md

@@ -0,0 +1,651 @@
+# Reference Endpoints
+
+> Complete reference for Products, Geographies, Vessels, and Corporations entity endpoints.
+> For the entity resolution workflow (how to resolve names to IDs), see entity-resolution.md (pre-loaded).
+> This doc covers what the API supports -- full parameter tables, hierarchies, and SDK/REST examples.
+
+---
+
+## Entity Hierarchy Overview
+
+All Vortexa data endpoints require 64-char hex IDs. Use these reference endpoints to resolve human-readable names.
+
+| Entity Type | SDK Class | Hierarchy (widest to most specific) | Key Filter |
+|---|---|---|---|
+| Product | `Products` | group > group_product > category > grade | `filter_layer` |
+| Geography | `Geographies` | wider_shipping_region > shipping_region_v2 > region > country > port > terminal | `filter_layer` |
+| Corporation | `Corporations` | effective_controller > commercial_owner > time_charterer > charterer | (none in SDK) |
+| Vessel | `Vessels` | oil / lpg / lng > grouped class > detailed class | `vessel_classes` |
+
+---
+
+## Products
+
+### Hierarchy
+
+```
+group (widest)
+ +-- group_product
+      +-- category
+           +-- grade (most specific)
+```
+
+| Layer | Example | When to Use |
+|---|---|---|
+| `group` | Crude & Condensates, Clean Petroleum Products, Dirty Petroleum Products, LNG, LPG/NGL | High-level commodity analysis |
+| `group_product` | Crude, Condensates, Gasoline/Naphtha, Fuel Oil, Gasoil/Diesel | Product family breakdown |
+| `category` | Medium-Sour, Light-Sweet, Diesel/Gasoil | Mid-level product classification |
+| `grade` | Arab Light, Bonny Light, Grane | Specific crude grade or refined product |
+
+### Product Groups (Top Level)
+
+These are the root-level product groups in Vortexa:
+- Crude & Condensates
+- Clean Petroleum Products
+- Dirty Petroleum Products
+- LNG
+- LPG/NGL
+- Chemicals
+- Vegetable Oils
+
+### SDK Methods
+
+```python
+from vortexasdk import Products
+
+# Search by name with layer filter
+df = Products().search(term="Arab Light", filter_layer="grade").to_df()
+
+# Search multiple terms
+df = Products().search(term=["diesel", "fuel oil", "grane"]).to_df("all")
+
+# Get children of a parent product
+df = Products().search(product_parent="<parent_id>").to_df()
+
+# Lookup by ID
+record = Products().reference(id="abc123...")
+```
+
+**search() parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `term` | str or List[str] | Product name(s) to search |
+| `ids` | str or List[str] | Specific product IDs |
+| `product_parent` | str or List[str] | Parent product ID(s) -- returns direct children |
+| `exact_term_match` | bool | Default `False` |
+| `filter_layer` | str | One of: `group`, `group_product`, `category`, `grade` |
+
+**Default DataFrame columns:** `id`, `name`, `layer.0`, `parent.0.name`
+
+**Full columns** (use `columns="all"`): includes `parent.0.id`, `parent.0.layer.0`, `meta.api_min`, `meta.api_max`, `meta.sulphur_min`, `meta.sulphur_max`, `ref_type`, `leaf`
+
+### REST API Alternative
+
+```python
+import requests
+
+base = "https://api.vortexa.com"
+headers = {"x-api-key": VORTEXA_API_KEY}
+
+payload = {"term": "Arab Light", "filter_layer": ["grade"], "size": 10}
+resp = requests.post(f"{base}/v5/reference/products", headers=headers, json=payload)
+products = resp.json()["data"]
+```
+
+**REST-specific parameters (not in SDK):**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `product_parent` | str | Parent ID or `"TOP_LEVEL"` to get root-level products |
+| `product_ancestor` | str[] | Ancestor IDs (returns all descendants) |
+| `allowTopLevelProducts` | bool | Default `true`. Include top-level products |
+
+### Product Entries in API Responses
+
+Cargo movement/voyage responses embed one product entry per hierarchy layer:
+
+```json
+[
+  {"id": "...", "layer": "group", "label": "Crude & Condensates", "probability": 0.94, "source": "model"},
+  {"id": "...", "layer": "group_product", "label": "Crude", "probability": 0.94, "source": "model"},
+  {"id": "...", "layer": "category", "label": "Medium-Sour", "probability": 0.94, "source": "model"},
+  {"id": "...", "layer": "grade", "label": "Arab Light", "probability": 0.94, "source": "model"}
+]
+```
+
+To extract a specific level: filter where `layer == "grade"` (or whichever level you need).
+
+### CRITICAL RULES -- Products
+
+- **ALWAYS** specify `filter_layer` to avoid matching the wrong hierarchy level
+- **ALWAYS** verify the `layer` and `name` columns in results -- fuzzy matching may return grades when you want the group
+- **NEVER** assume "crude" matches only one product -- without `filter_layer`, it returns group, group_product, and grade matches
+- **ALWAYS** set `size` >= 10 for resolution searches (default `size=1` may return the wrong match)
+
+---
+
+## Geographies
+
+### Hierarchy
+
+```
+wider_shipping_region (widest)
+ +-- shipping_region_v2
+      +-- region
+           +-- country
+                +-- port
+                     +-- terminal (most specific)
+```
+
+**Additional geography layers (not in main hierarchy):**
+- `sts_zone` -- Ship-to-ship transfer zones
+- `waypoint` -- Chokepoints and transit points (e.g. Suez, Panama)
+- `trading_block`, `trading_region`, `trading_subregion` -- Trade-oriented groupings
+- `country_zone`, `state_or_province` -- Sub-country divisions
+- `basin` -- Ocean basins
+- `storage`, `storage_terminal` -- Onshore storage locations
+
+### SDK Methods
+
+```python
+from vortexasdk import Geographies
+
+# Search by name with layer filter
+df = Geographies().search(term="Rotterdam", filter_layer="port").to_df()
+
+# Search multiple terms
+df = Geographies().search(term=["Liverpool", "Southampton"]).to_df()
+
+# Exact match only
+df = Geographies().search(term="China", exact_term_match=True, filter_layer="country").to_df()
+
+# Lookup by ID
+record = Geographies().reference(id="abc123...")
+```
+
+**search() parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `term` | str or List[str] | Geography name(s) to search |
+| `exact_term_match` | bool | Default `False`. If `True`, only exact name matches |
+| `filter_layer` | str | One of: `terminal`, `port`, `country`, `country_zone`, `shipping_region`, `shipping_region_v2`, `wider_shipping_region`, `region`, `alternative_region`, `trading_block`, `trading_region`, `trading_subregion`, `state_or_province`, `sts_zone`, `waypoint`, `storage`, `storage_terminal`, `basin`, `root` |
+
+**Default DataFrame columns:** `id`, `name`, `layer`
+
+**REST-specific parameters (not in SDK):**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `geography_parent` | str[] | Parent ID(s) or `"TOP_LEVEL"` to get root-level geographies |
+| `only_root` | bool | Omit parent/hierarchy data from results |
+
+### Common Geography Lookups
+
+| Common Name / Abbreviation | filter_layer | Vortexa Name | Notes |
+|---|---|---|---|
+| "China", "US", "Saudi Arabia" | `country` | China, United States, Saudi Arabia | Country names |
+| "Rotterdam", "Fujairah", "Ras Tanura" | `port` | Rotterdam [NL], Fujairah, Ras Tanura | Port names |
+| "Middle East", "Asia", "Europe" | `region` | Middle East/North Africa, Asia, Europe | Broad regions |
+| "AG", "Arabian Gulf", "Persian Gulf" | `shipping_region_v2` | Arabian/Persian Gulf | Shipping regions |
+| "USG", "US Gulf Coast" | `shipping_region_v2` | US Gulf Coast | Shipping regions |
+| "WAF", "West Africa" | `shipping_region_v2` | West Africa | Shipping regions |
+| "ARA" | `port` (multiple) | Amsterdam, Rotterdam, Antwerp | Resolve each port separately |
+| "PADD I", "East Coast" | `shipping_region_v2` | US Atlantic Coast | US regional |
+| "Suez Canal", "Panama Canal" | `waypoint` | Suez Canal, Panama Canal | Chokepoints |
+
+### REST API Alternative
+
+```python
+import requests
+
+base = "https://api.vortexa.com"
+headers = {"x-api-key": VORTEXA_API_KEY}
+
+payload = {"term": "Rotterdam", "filter_layer": ["port"], "size": 10}
+resp = requests.post(f"{base}/v5/reference/geographies", headers=headers, json=payload)
+geos = resp.json()["data"]
+```
+
+### Geography Entries in API Responses
+
+Location arrays in cargo events contain one entry per hierarchy layer:
+
+```json
+[
+  {"id": "...", "layer": "terminal", "label": "Poleng Marine Terminal", "probability": 1, "source": "model"},
+  {"id": "...", "layer": "port", "label": "Poleng Field [ID]", "probability": 1, "source": "model"},
+  {"id": "...", "layer": "country", "label": "Indonesia", "probability": 1, "source": "model"},
+  {"id": "...", "layer": "region", "label": "Asia", "probability": 1, "source": "model"}
+]
+```
+
+### CRITICAL RULES -- Geographies
+
+- **ALWAYS** specify `filter_layer` -- "China" without a layer returns ports, regions, AND the country
+- **NEVER** use a port ID when a country was intended (volumes will be drastically wrong)
+- **NEVER** search geographies without `filter_layer` in production queries
+- **ALWAYS** use `exact_term_match=True` for well-known names to avoid fuzzy noise
+- **ALWAYS** set `size` >= 10 for resolution searches
+
+---
+
+## Vessels
+
+### SDK Methods
+
+```python
+from vortexasdk import Vessels
+
+# Search by name
+df = Vessels().search(term="ocean", vessel_classes="oil_vlcc").to_df()
+
+# Search by IMO
+df = Vessels().search(ids=[9779836]).to_df(columns="all")
+
+# Filter by class and scrubber
+df = Vessels().search(
+    vessel_classes=["oil_aframax", "oil_suezmax"],
+    vessel_scrubbers="inc"
+).to_df()
+
+# Lookup by ID
+record = Vessels().reference(id="abc123...")
+```
+
+**search() parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `term` | str or List[str] | Vessel name(s) to search. Also matches `related_names`. |
+| `ids` | str or List[str] | Vessel IDs, IMO numbers, or MMSI numbers |
+| `vessel_classes` | str or List[str] | Vessel class filter (see class reference below) |
+| `vessel_scrubbers` | str | `"disabled"` (default), `"inc"`, or `"exc"` |
+| `exact_term_match` | bool | Default `False` |
+
+**Default DataFrame columns:** `id`, `name`, `imo`, `vessel_class`
+
+**Additional columns** (use `columns="all"`): `mmsi`, `dwt`, `cubic_capacity`, `related_names`, `year`, `flag`, `scrubber`, `ice_class`, `propulsion`, `tags`
+
+**REST-specific parameters (not in SDK):**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `vessel_tags` | object[] | Filter by vessel tags (e.g. dark activity, FSO) |
+| `vessel_tags_excluded` | object[] | Exclude vessels with these tags |
+| `dwt_min` / `dwt_max` | number | DWT range filter (0-550,000) |
+| `ship_to_ship_only` | bool | Only STS-capable vessels |
+
+### Vessel Class Reference
+
+**User Term to API Vessel Class mapping:**
+
+| User Says | API `vessel_classes` Value | Typical Size |
+|---|---|---|
+| "VLCC" | `oil_vlcc` | 200,000+ DWT |
+| "Suezmax" | `oil_suezmax` | 120,000-200,000 DWT |
+| "Aframax" | `oil_aframax` | 80,000-120,000 DWT |
+| "Panamax" (oil) | `oil_panamax` | 55,000-80,000 DWT |
+| "MR2", "Handymax" | `oil_handymax` or `oil_mr2` | 40,000-55,000 DWT |
+| "MR1", "Handysize" | `oil_handysize` or `oil_mr1` | 25,000-40,000 DWT |
+| "LR1" | `oil_lr1` | 55,000-80,000 DWT |
+| "LR2" | `oil_lr2` | 80,000-120,000 DWT |
+| "LR3" | `oil_lr3` | 120,000-200,000 DWT |
+| "Coastal tanker" | `oil_coastal` | <25,000 DWT |
+| "VLGC" | `lpg_vlgc` | 60,000+ CBM |
+| "LGC" | `lpg_lgc` | 35,000-60,000 CBM |
+| "MGC" | `lpg_mgc` | 15,000-35,000 CBM |
+| "Q-Flex", "Q-Max" | `lng_q_flex`, `lng_q_max` | Qatar Q-class mega |
+| "LNG carrier" | `lng_conventional_lng` | Standard LNG |
+| "All oil tankers" | `oil` | All oil subclasses |
+| "All LPG carriers" | `lpg` | All LPG subclasses |
+| "All LNG carriers" | `lng` | All LNG subclasses |
+
+**Grouped classes** (each group aggregates multiple detailed classes):
+
+| Grouped Class | Detailed Classes |
+|---|---|
+| `oil_suezmax_lr3` | `oil_suezmax`, `oil_lr3` |
+| `oil_aframax_lr2` | `oil_aframax`, `oil_lr2` |
+| `oil_panamax_lr1` | `oil_panamax`, `oil_lr1` |
+| `oil_handymax_mr2` | `oil_handymax`, `oil_mr2` |
+| `oil_handysize_mr1` | `oil_handysize`, `oil_mr1` |
+| `lpg_vlgc_vlec` | `lpg_vlgc`, `lpg_vlec` |
+| `lpg_sgc` | `lpg_handysize`, `lpg_coasters` |
+| `lng_conventional_lng` | `lng_two_stroke`, `lng_tfde_dfde`, `lng_steam`, `lng_ssd` |
+
+Top-level aggregates: `oil`, `lpg`, `lng` -- match all subclasses within that group.
+
+### Vessel Entities in API Responses
+
+Vessel objects in cargo movement responses contain:
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | string | Vortexa vessel ID (64-char hex) |
+| `imo` | number | IMO number |
+| `mmsi` | number | MMSI number |
+| `name` | string | Vessel name |
+| `dwt` | number | Deadweight tonnage |
+| `cubic_capacity` | number | Cubic capacity (m3) |
+| `vessel_class` | string | Vessel class code |
+| `corporate_entities` | array | Array of corporate entity objects |
+| `start_timestamp` | string | When cargo was loaded onto this vessel |
+| `end_timestamp` | string or null | When cargo left (null if still onboard) |
+| `voyage_id` | string or null | Linked voyage ID |
+| `tags` | array | Time-bound vessel tags (e.g. FSO, dark activity) |
+| `status` | string | e.g. `vessel_status_laden_known`, `vessel_status_ballast` |
+| `year` | number or null | Build year |
+| `flag` | array | Flag state info |
+| `scrubber` | array | Scrubber info |
+
+### REST API Alternative
+
+```python
+import requests
+
+base = "https://api.vortexa.com"
+headers = {"x-api-key": VORTEXA_API_KEY}
+
+# Search by IMO
+payload = {"term": [9779836], "size": 10}
+resp = requests.post(f"{base}/v5/reference/vessels", headers=headers, json=payload)
+vessels = resp.json()["data"]
+
+# Get vessel by ID
+vessel_id = "1f6d6ab80d90846cedddf1a4b470faf566fd72595e853bc769185fac6ae7af70"
+resp = requests.get(f"{base}/v5/reference/vessels/{vessel_id}", headers=headers)
+vessel = resp.json()["data"][0]
+
+# Get IDs only (lighter response)
+payload = {"vessel_classes": ["oil_vlcc"], "size": 500}
+resp = requests.post(f"{base}/v5/reference/vessels-ids", headers=headers, json=payload)
+# Supports return_type: "short" for 16-char truncated IDs
+```
+
+### CRITICAL RULES -- Vessels
+
+- **NEVER** pass IMO numbers as strings -- the API requires integers in the `ids` or `term` array
+- **ALWAYS** use `vessel_classes` filter in Vessels endpoint for name/IMO/class lookup only
+- Vessel class filtering for data queries (CargoMovements/Voyages) happens via `filter_vessel_classes` in the query, not in the Vessels reference endpoint
+- For vessel class filtering in CM/Voyages: use `filter_vessel_classes=["oil_vlcc"]` directly -- no ID resolution needed
+- **ALWAYS** set `size` >= 10 for resolution searches
+
+---
+
+## Corporations
+
+### SDK Methods
+
+```python
+from vortexasdk import Corporations
+
+# Search by name
+df = Corporations().search(term="BAHRI").to_df()
+
+# Exact match
+df = Corporations().search(term="CHEVRON", exact_term_match=True).to_df()
+
+# Lookup by ID
+record = Corporations().reference(id="abc123...")
+```
+
+**search() parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `term` | str or List[str] | Corporation name(s) to search |
+| `exact_term_match` | bool | Default `False` |
+
+**Default DataFrame columns:** `id`, `name`, `corporate_entity_type`
+
+### Corporate Hierarchy
+
+```
+effective_controller (ultimate owner)
+ +-- commercial_owner
+      +-- time_charterer
+           +-- charterer (voyage-level)
+```
+
+Additional corporate entity types (API only):
+- `cargo_trader` -- Commodity trading house
+- `shipper` -- Party shipping the cargo
+- `consignee` -- Receiving party
+- `buyer_seller` -- Transaction counterparty
+
+### REST API Alternative (Required for Entity Type Filtering)
+
+The SDK `Corporations` class wraps the API's `/reference/charterers` endpoint but does **NOT** expose `corporateEntityType` filtering. Use REST directly when you need to filter by role:
+
+```python
+import requests
+
+base = "https://api.vortexa.com"
+headers = {"x-api-key": VORTEXA_API_KEY}
+
+# Search corporations by entity type (REST only)
+payload = {
+    "term": "CHEVRON",
+    "corporateEntityType": ["effective_controller"],
+    "size": 10
+}
+resp = requests.post(f"{base}/v5/reference/charterers", headers=headers, json=payload)
+corps = resp.json()["data"]
+```
+
+**REST `corporateEntityType` values:** `effective_controller`, `charterer`, `time_charterer`, `commercial_owner`, `cargo_trader`, `shipper`, `consignee`, `buyer_seller`, `all`
+
+### Corporate Entities in API Responses
+
+The `corporate_entities` array in vessel objects contains one entry per role:
+
+```json
+[
+  {"id": "...", "layer": "effective_controller", "label": "BAHRI", "probability": 1, "source": "external"},
+  {"id": "...", "layer": "charterer", "label": "CHEVRON", "probability": 1, "source": "external"}
+]
+```
+
+Not all roles are always present -- a vessel may have an effective_controller but no charterer.
+
+### CRITICAL RULES -- Corporations
+
+- **SDK limitation:** `Corporations` class does NOT expose `corporateEntityType` filter -- use REST API for role-based filtering
+- **ALWAYS** use `exact_term_match=True` when searching well-known company names to avoid fuzzy noise (e.g. "COS" returns COSCO, COSMO OIL, etc.)
+- **NEVER** assume a single corporate entity has only one role -- the same company can appear as both effective_controller and charterer
+- **ALWAYS** set `size` >= 10 for resolution searches
+
+---
+
+## Additional Reference Endpoints
+
+These endpoints are less frequently used but available for specialized queries.
+
+### Attributes
+
+Resolve vessel attribute IDs (propulsion, scrubber type, ice class) to human-readable labels.
+
+```python
+from vortexasdk import Attributes
+
+# Get all scrubber types
+df = Attributes().search(type="scrubber").to_df()
+
+# Resolve specific attribute IDs from vessel data
+propulsion_id = "3ace0e050724707b"
+attr = Attributes().search(ids=[propulsion_id]).to_df()
+# Returns: id, name="DFDE", type="propulsion"
+```
+
+**search() parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `type` | str | One of: `ice_class`, `propulsion`, `scrubber` |
+| `term` | str or List[str] | Attribute name to search |
+| `ids` | str or List[str] | Specific attribute IDs to resolve |
+
+### Asset Tanks
+
+Search onshore oil storage tanks.
+
+```python
+from vortexasdk import AssetTanks
+
+df = AssetTanks().search(storage_type=["refinery"]).to_df()
+df = AssetTanks().search(location_ids=["<geo_id>"], crude_confidence=["confirmed"]).to_df()
+```
+
+**Key parameters:** `storage_type` (refinery/commercial/spr), `crude_confidence` (confirmed/probable/unlikely), `location_ids`, `corporate_entity_ids`
+
+### Storage Terminals
+
+```python
+from vortexasdk import StorageTerminals
+
+df = StorageTerminals().search(term=["Military"]).to_df()
+```
+
+### Refineries
+
+```python
+from vortexasdk import Refineries
+
+df = Refineries().search(term="San").to_df(columns=["name", "country_name"])
+df = Refineries().search(status="Active").to_df(columns="all")
+df = Refineries().search(owner_id=["<corporate_id>"]).to_df()
+```
+
+**Key parameters:** `status` (Active/Shut/Unknown/Upcoming), `owner_id`, `operator_id`, `refinery_name`
+
+---
+
+## Worked Examples
+
+### 1. Resolve geography IDs for use in cargo/voyage queries
+
+```python
+from vortexasdk import Geographies
+
+targets = {"China": "country", "Singapore": "country", "Rotterdam": "port"}
+ids = {}
+for name, layer in targets.items():
+    result = Geographies().search(term=name, exact_term_match=True, filter_layer=layer).to_df()
+    if not result.empty:
+        ids[name] = result.iloc[0]["id"]
+```
+
+### 2. Get all crude grades under a category
+
+```python
+from vortexasdk import Products
+
+# First find Medium-Sour category
+category = Products().search(term="Medium-Sour", exact_term_match=True, filter_layer="category").to_df()
+parent_id = category.iloc[0]["id"]
+
+# Get all grades under it
+grades = Products().search(product_parent=parent_id, filter_layer="grade").to_df()
+```
+
+### 3. Find all VLCCs owned by a specific company
+
+```python
+from vortexasdk import Corporations, Vessels
+
+corp = Corporations().search(term="BAHRI", exact_term_match=True).to_df()
+vlccs = Vessels().search(vessel_classes="oil_vlcc").to_df(columns="all")
+```
+
+### 4. Look up vessel by IMO number
+
+```python
+from vortexasdk import Vessels
+
+df = Vessels().search(ids=[9779836]).to_df(columns=["id", "name", "imo", "mmsi", "dwt", "vessel_class"])
+```
+
+### 5. Get all active refineries
+
+```python
+from vortexasdk import Refineries
+
+df = Refineries().search(status="Active").to_df(columns="all")
+# Filter by country_name in the DataFrame
+```
+
+### 6. Resolve attribute IDs from vessel data
+
+```python
+from vortexasdk import Attributes
+
+propulsion_id = "3ace0e050724707b"
+attr = Attributes().search(ids=[propulsion_id]).to_df()
+# Returns: id, name="DFDE", type="propulsion"
+```
+
+---
+
+## Error Recovery
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Only 1 result returned | Default `size` is 1 | Set `size=500` or higher |
+| No results for a known entity | Name differs from Vortexa label | Try partial name, remove special characters, set `exact_term_match=False` |
+| SDK `Corporations` doesn't filter by entity type | SDK doesn't expose `corporateEntityType` | Use REST API `/v5/reference/charterers` directly |
+| Geography search returns too many results | Common name matches many entries | Add `filter_layer` to narrow results |
+| Vessel search by IMO returns nothing | IMO passed as string instead of integer | Pass IMO as integer in the `ids` or `term` array |
+| Product hierarchy unclear | Don't know which layer a product belongs to | Search without `filter_layer`, check the `layer` field in results |
+| Corporate entity ID doesn't match search | Response uses 16-char truncated IDs | Use the 64-char ID from the entity's `id` field, or search by name |
+
+---
+
+## ID Formats
+
+| Format | Length | Used In | Example |
+|---|---|---|---|
+| Full hex ID | 64 characters | All API filter parameters, entity lookups | `a1b2c3d4e5f6...` (64 chars) |
+| Truncated hex ID | 16 characters | `cargo_movement_id` in joins, voyage links, `vessels-ids` with `return_type: "short"` | `a1b2c3d4e5f6a7b8` |
+
+**ALWAYS** use full 64-char IDs for API filter parameters. Truncated 16-char IDs appear in cross-endpoint joins (e.g. matching cargo movements to voyages) but are not valid for filter parameters.
+
+---
+
+## Defaults and Pagination
+
+| Parameter | Default | Notes |
+|---|---|---|
+| `size` | 1 | **Always set explicitly.** Default returns only 1 record. Max: 10,000 |
+| `search_after` | -- | Use `next_request.search_after` from previous response for pagination |
+| `exact_term_match` (SDK) | `False` | Fuzzy matching by default |
+
+**Pagination pattern (REST):**
+
+```python
+import requests
+
+all_data = []
+payload = {"term": "crude", "filter_layer": ["grade"], "size": 500}
+
+while True:
+    resp = requests.post(f"{base}/v5/reference/products", headers=headers, json=payload)
+    result = resp.json()
+    all_data.extend(result["data"])
+    if "next_request" not in result or not result["next_request"]:
+        break
+    payload["search_after"] = result["next_request"]["search_after"]
+    payload["size"] = result["next_request"]["size"]
+```
+
+**Common API response structure:**
+
+```json
+{
+  "total": 150,
+  "data": [<records>],
+  "metadata": [...],
+  "next_request": {"size": 500, "search_after": {...}}
+}
+```