Xeneta Ocean API
The Ocean API from Xeneta — 13 operation(s) for ocean.
OpenAPI Specification
openapi: 3.1.0
info:
title: xeneta-api-30 Air Ocean API
version: '3.0'
servers:
- url: https://api.xeneta.com/v3.0
security:
- sec0: []
tags:
- name: Ocean
paths:
/ocean/market-rates:
get:
summary: Get market rates
description: Returns ocean freight market rates within the specified parameters.
operationId: get-ocean-market-rates
parameters:
- name: origin
in: query
description: Defines the origin location of the requested market rate data. Can be either a UN/LOCODE or a region as defined in Xeneta's [geo-hierarchy](https://www.xeneta.com/hubfs/2025-ocean-geo/xeneta-ocean-geo.html). For example, `CNSGH` or `china_east_main`.
required: true
schema:
type: string
default: CNSGH
- name: destination
in: query
description: Defines the destination location of the requested market rate data. Can be either a UN/LOCODE or a region as defined in Xeneta's [geo-hierarchy](https://www.xeneta.com/hubfs/2025-ocean-geo/xeneta-ocean-geo.html). For example, `NLRTM` or `north_europe_main`.
required: true
schema:
type: string
default: NLRTM
- name: date_from
in: query
description: Defines the start date of the date range for the requested market rates in the `YYYY-MM-DD` format. The total range cannot exceed 31 days.
required: true
schema:
type: string
format: date
default: '2023-02-01'
- name: date_to
in: query
description: Defines the end date of the date range for the requested market rates in the `YYYY-MM-DD` format. The total range cannot exceed 31 days.<br><br>Using a future date will return contracted rates that are valid up to 10 days (when `contract_length` is set to `short`) or 3 months (when `contract_length` is set to `long`) beyond the current date.
required: true
schema:
type: string
format: date
default: '2023-02-05'
- name: contract_length
in: query
description: Defines the type of contract for the requested market rate data. Accepted values are `long` or `short`.
required: true
schema:
type: string
default: long
- name: contracted_within
in: query
description: Defines the maximum age of the contracts to be included in the requested market rate data, relative to each day. Accepted values include `all`, `3months` and `6months`. Using any value other than `all` when `contract_length` is set to `short` will return an error.
required: true
schema:
type: string
default: 6months
- name: container_type
in: query
description: Defines the container type of the requested market rate data. Accepted values include `20DC`, `20RE`, `20TK`, `40DC`, `40RH` and `40HC`.
required: true
schema:
type: string
default: 40DC
- name: thc_methodology
in: query
description: Defines whether the requested market rate data should include the terminal handling charge. Accepted values include `meth`, `othc`, `dthc`, `none` and `both`. Selecting `meth` will use Xeneta's default [methodology](https://help.xeneta.com/docs/terminal-handling-charges) for the requested `origin` and `destination`.
required: true
schema:
type: string
default: meth
- name: bump_up
in: query
description: Defines whether to allow rates from larger geographic regions in the response if there is not enough data for the requested `origin` and `destination`. Using `false` when there is no rate data available for the requested `origin` and `destination` will return an error.
schema:
type: boolean
default: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"market_rates_by_day\": {\n \"high\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 10396\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 10396\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 10396\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 9350\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 9350\n }\n ],\n \"low\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 1490\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 1490\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 1490\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 1487\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 1487\n }\n ],\n \"mean\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 3685\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 3685\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 3685\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 3506\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 3506\n }\n ],\n \"median\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 2256\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 2256\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 2256\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 2250\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 2250\n }\n ],\n \"midhigh\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 4939\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 4939\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 4939\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 4500\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 4500\n }\n ],\n \"midlow\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 1836\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 1835\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 1835\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 1827\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 1827\n }\n ],\n \"rate_quality\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": \"30 +\"\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": \"30 +\"\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": \"30 +\"\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": \"30 +\"\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": \"30 +\"\n }\n ]\n },\n \"meta\": {\n \"actual_destination\": {\n \"allow_aggregation\": true,\n \"geo_level\": 4,\n \"location\": \"NLRTM\",\n \"name\": \"Rotterdam\",\n \"type\": \"Port\"\n },\n \"actual_origin\": {\n \"allow_aggregation\": true,\n \"geo_level\": 6,\n \"location\": \"CNSGH\",\n \"name\": \"Shanghai\",\n \"type\": \"Port\"\n },\n \"aggregation_allowed\": true,\n \"asked_destination\": {\n \"allow_aggregation\": true,\n \"geo_level\": 4,\n \"location\": \"NLRTM\",\n \"name\": \"Rotterdam\",\n \"type\": \"Port\"\n },\n \"asked_origin\": {\n \"allow_aggregation\": true,\n \"geo_level\": 6,\n \"location\": \"CNSGH\",\n \"name\": \"Shanghai\",\n \"type\": \"Port\"\n },\n \"default_thc_methodology\": {\n \"dthc_applicable\": true,\n \"othc_applicable\": true,\n \"thc_class\": \"none\"\n },\n \"rate_quality\": \"30 +\"\n }\n}"
schema:
type: object
properties:
market_rates_by_day:
type: object
properties:
high:
type: array
items:
type: object
properties:
day:
type: string
example: '2023-02-01'
value:
type: integer
example: 10396
default: 0
low:
type: array
items:
type: object
properties:
day:
type: string
example: '2023-02-01'
value:
type: integer
example: 1490
default: 0
mean:
type: array
items:
type: object
properties:
day:
type: string
example: '2023-02-01'
value:
type: integer
example: 3685
default: 0
median:
type: array
items:
type: object
properties:
day:
type: string
example: '2023-02-01'
value:
type: integer
example: 2256
default: 0
midhigh:
type: array
items:
type: object
properties:
day:
type: string
example: '2023-02-01'
value:
type: integer
example: 4939
default: 0
midlow:
type: array
items:
type: object
properties:
day:
type: string
example: '2023-02-01'
value:
type: integer
example: 1836
default: 0
rate_quality:
type: array
items:
type: object
properties:
day:
type: string
example: '2023-02-01'
value:
type: string
example: 30 +
meta:
type: object
properties:
actual_destination:
type: object
properties:
allow_aggregation:
type: boolean
example: true
default: true
geo_level:
type: integer
example: 4
default: 0
location:
type: string
example: NLRTM
name:
type: string
example: Rotterdam
type:
type: string
example: Port
actual_origin:
type: object
properties:
allow_aggregation:
type: boolean
example: true
default: true
geo_level:
type: integer
example: 6
default: 0
location:
type: string
example: CNSGH
name:
type: string
example: Shanghai
type:
type: string
example: Port
aggregation_allowed:
type: boolean
example: true
default: true
asked_destination:
type: object
properties:
allow_aggregation:
type: boolean
example: true
default: true
geo_level:
type: integer
example: 4
default: 0
location:
type: string
example: NLRTM
name:
type: string
example: Rotterdam
type:
type: string
example: Port
asked_origin:
type: object
properties:
allow_aggregation:
type: boolean
example: true
default: true
geo_level:
type: integer
example: 6
default: 0
location:
type: string
example: CNSGH
name:
type: string
example: Shanghai
type:
type: string
example: Port
default_thc_methodology:
type: object
properties:
dthc_applicable:
type: boolean
example: true
default: true
othc_applicable:
type: boolean
example: true
default: true
thc_class:
type: string
example: none
rate_quality:
type: string
example: 30 +
deprecated: false
tags:
- Ocean
/ocean/estimated-rates:
get:
summary: Get estimated rates
description: Returns estimated rate within the specified parameters on the port-to-port level only.
operationId: get-estimated-rates
parameters:
- name: origin
in: query
description: Defines the origin port of the requested estimated rate data. Only UN/LOCODE values matching Xeneta's [geo-hierarchy](https://www.xeneta.com/hubfs/2025-ocean-geo/xeneta-ocean-geo.html) are supported, anything else will result in an error or an empty response.
required: true
schema:
type: string
default: CNSGH
- name: destination
in: query
description: Defines the destination port of the requested estimated rate data. Only UN/LOCODE values matching Xeneta's [geo-hierarchy](https://www.xeneta.com/hubfs/2025-ocean-geo/xeneta-ocean-geo.html) are supported, anything else will result in an error or an empty response.
required: true
schema:
type: string
default: USPHL
- name: date_from
in: query
description: Defines the start date of the date range for the requested estimated rates in the `YYYY-MM-DD` format.
required: true
schema:
type: string
format: date
default: '2023-02-01'
- name: date_to
in: query
description: Defines the end date of the date range for the requested estimated rates in the `YYYY-MM-DD` format. The total range cannot exceed 31 days.
required: true
schema:
type: string
format: date
default: '2023-02-05'
- name: contract_length
in: query
description: Defines the type of contract for the requested estimated rate data. Accepted values are `long` or `short`. The total range cannot exceed 31 days.
required: true
schema:
type: string
default: long
- name: contracted_within
in: query
description: Defines the maximum age of the contracts to be included in the requested estimated rate data, relative to each day. Accepted values include `all`, `3months` and `6months`. Using any value other than `all` when `contract_length` is set to `short` will return an error.
required: true
schema:
type: string
default: all
- name: container_type
in: query
description: Defines the container type of the requested market rate data. Accepted values include `20DC`, `20RE`, `20TK`, `40DC`, `40RH` and `40HC`.
required: true
schema:
type: string
default: 40DC
- name: thc_methodology
in: query
description: Defines whether the requested market rate data should include the terminal handling charge. Accepted values include `meth`, `othc`, `dthc`, `none` and `both`. Selecting `meth` will use Xeneta's default [methodology](https://help.xeneta.com/docs/terminal-handling-charges) for the requested `origin` and `destination`.
required: true
schema:
type: string
default: meth
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"estimated_rates_by_day\": {\n \"mean\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 7893\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 7893\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 7893\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 7893\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 7893\n }\n ]\n },\n \"meta\": {\n \"asked_origin\": {\n \"location\": \"CNSGH\",\n \"name\": \"Shanghai\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"geo_level\": 6\n },\n \"asked_destination\": {\n \"location\": \"USPHL\",\n \"name\": \"Philadelphia, PA\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"geo_level\": 5\n },\n \"default_thc_methodology\": {\n \"thc_class\": \"dthc\",\n \"dthc_applicable\": true,\n \"othc_applicable\": true\n }\n }\n}"
schema:
type: object
properties:
estimated_rates_by_day:
type: object
properties:
mean:
type: array
items:
type: object
properties:
day:
type: string
example: '2023-02-01'
value:
type: integer
example: 7893
default: 0
meta:
type: object
properties:
asked_origin:
type: object
properties:
location:
type: string
example: CNSGH
name:
type: string
example: Shanghai
type:
type: string
example: Port
allow_aggregation:
type: boolean
example: true
default: true
geo_level:
type: integer
example: 6
default: 0
asked_destination:
type: object
properties:
location:
type: string
example: USPHL
name:
type: string
example: Philadelphia, PA
type:
type: string
example: Port
allow_aggregation:
type: boolean
example: true
default: true
geo_level:
type: integer
example: 5
default: 0
default_thc_methodology:
type: object
properties:
thc_class:
type: string
example: dthc
dthc_applicable:
type: boolean
example: true
default: true
othc_applicable:
type: boolean
example: true
default: true
deprecated: false
tags:
- Ocean
/ocean/my-prices:
get:
summary: Get my prices
description: Returns your imported rates for a specific port pair.
operationId: get-my-prices
parameters:
- name: origin
in: query
description: Defines the origin port of your requested imported rates. Only UN/LOCODE values matching Xeneta's [geo-hierarchy](https://www.xeneta.com/hubfs/2025-ocean-geo/xeneta-ocean-geo.html) are supported. For example, `CNSGH`.
required: true
schema:
type: string
default: CNSGH
- name: destination
in: query
description: Defines the destination port of your requested imported rates. Only UN/LOCODE values matching Xeneta's [geo-hierarchy](https://www.xeneta.com/hubfs/2025-ocean-geo/xeneta-ocean-geo.html) are supported. For example, `NLRTM`.
required: true
schema:
type: string
default: NLRTM
- name: date_from
in: query
description: Defines the start date of the date range for your requested imported rates in the `YYYY-MM-DD` format. The total range cannot exceed 31 days.
required: true
schema:
type: string
format: date
default: '2023-02-01'
- name: date_to
in: query
description: Defines the end date of the date range for your requested imported rates in the `YYYY-MM-DD` format. The total range cannot exceed 31 days.
required: true
schema:
type: string
format: date
default: '2023-02-05'
- name: container_type
in: query
description: Defines the container type of your requested imported rates. Accepted values include `20DC`, `20RE`, `20TK`, `40DC`, `40RH` and `40HC`.
required: true
schema:
type: string
default: 40DC
- name: thc_methodology
in: query
description: Defines whether your requested imported rates should include the terminal handling charge. Accepted values include `meth`, `othc`, `dthc`, `none` and `both`. Selecting `meth` will use Xeneta's default [methodology](https://help.xeneta.com/docs/terminal-handling-charges) for the requested `origin` and `destination`.
required: true
schema:
type: string
default: meth
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"meta\": {\n \"asked_origin\": {\n \"location\": \"CNSGH\",\n \"name\": \"Shanghai\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"geo_level\": 6\n },\n \"asked_destination\": {\n \"location\": \"NLRTM\",\n \"name\": \"Rotterdam\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"geo_level\": 4\n },\n \"thc_methodology\": \"none\"\n },\n \"my_prices\": [\n {\n \"origin\": {\n \"location\": \"CNSGH\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Shanghai\"\n },\n \"destination\": {\n \"location\": \"NLRTM\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Rotterdam\"\n },\n \"supplier_name\": \"Carrier/FF 01\",\n \"rate_info\": \"Update 2023-01-01\",\n \"prices\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 2070\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 2070\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 2070\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 2070\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 2070\n }\n ]\n },\n {\n \"origin\": {\n \"location\": \"CNSGH\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Shanghai\"\n },\n \"destination\": {\n \"location\": \"NLRTM\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Rotterdam\"\n },\n \"supplier_name\": \"Carrier/FF 02\",\n \"rate_info\": \"Update 2023-01-01\",\n \"prices\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 1210\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 1198\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 1188\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 1188\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 1186\n }\n ]\n },\n {\n \"origin\": {\n \"location\": \"CNSGH\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Shanghai\"\n },\n \"destination\": {\n \"location\": \"NLRTM\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Rotterdam\"\n },\n \"supplier_name\": \"Carrier/FF 03\",\n \"rate_info\": \"Update 2023-01-01\",\n \"prices\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 1227\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 1215\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 1204\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 1204\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 1202\n }\n ]\n },\n {\n \"origin\": {\n \"location\": \"CNSGH\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Shanghai\"\n },\n \"destination\": {\n \"location\": \"NLRTM\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Rotterdam\"\n },\n \"supplier_name\": \"Carrier/FF 04\",\n \"rate_info\": \"Update 2023-01-01\",\n \"prices\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 3060\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 3030\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 3003\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 3004\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 2998\n }\n ]\n },\n {\n \"origin\": {\n \"location\": \"CNSGH\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Shanghai\"\n },\n \"destination\": {\n \"location\": \"NLRTM\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Rotterdam\"\n },\n \"supplier_name\": \"Carrier/FF 05\",\n \"rate_info\": \"Update 2023-01-01\",\n \"prices\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 1548\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 1533\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 1519\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 1520\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 1517\n }\n ]\n },\n {\n \"origin\": {\n \"location\": \"CNSGH\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Shanghai\"\n },\n \"destination\": {\n \"location\": \"NLRTM\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Rotterdam\"\n },\n \"supplier_name\": \"Carrier/FF 06\",\n \"rate_info\": \"Update 2023-01-01\",\n \"prices\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 7811\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 7735\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 7664\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 7669\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 7653\n }\n ]\n },\n {\n \"origin\": {\n \"location\": \"CNSGH\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Shanghai\"\n },\n \"destination\": {\n \"location\": \"NLRTM\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Rotterdam\"\n },\n \"supplier_name\": \"Carrier/FF 07\",\n \"rate_info\": \"Update 2023-01-01\",\n \"prices\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 1230\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 1218\n },\n {\n \"day\": \"2023-02-03\",\n \"value\": 1207\n },\n {\n \"day\": \"2023-02-04\",\n \"value\": 1208\n },\n {\n \"day\": \"2023-02-05\",\n \"value\": 1205\n }\n ]\n },\n {\n \"origin\": {\n \"location\": \"CNSGH\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Shanghai\"\n },\n \"destination\": {\n \"location\": \"NLRTM\",\n \"type\": \"Port\",\n \"allow_aggregation\": true,\n \"name\": \"Rotterdam\"\n },\n \"supplier_name\": \"Carrier/FF 09\",\n \"rate_info\": \"Update 2023-01-01\",\n \"prices\": [\n {\n \"day\": \"2023-02-01\",\n \"value\": 1696\n },\n {\n \"day\": \"2023-02-02\",\n \"value\": 1679\n },\n {\n \"day\": \"2
# --- truncated at 32 KB (95 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xeneta/refs/heads/main/openapi/xeneta-ocean-api-openapi.yml