NAV Navbar
Logo
Examples

Introduction

The Xeneta API is built using REST principles to enable client access to Xeneta endpoints. HTTPS is the communication protocol used across the API.

Response Codes

Error Code Description
200 OK – Successful request
400 Bad Request – Check input parameters
401 Unauthorized – Problem with API token

Authentication and Security

Request body:

url = "https://api.xeneta.com/v1/echo"
api_key = "test_flKdjskflsDsf43534dfsf"
headers = {"X-Auth": api_key}
requests.get(url, headers=headers)

Response body:

HTTP/1.1 200 OK
Server: nginx/1.11.5
Date: Mon, 09 Jan 2017 11:42:28 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1909
Last-Modified: Tue, 20 Dec 2016 13:28:01 GMT

All access to the Xeneta Web Services is done over TLS-encrypted connections. Non-encrypted access will not be allowed. Authentication requires Xeneta-issued API tokens. You must contact Xeneta in order to acquire an API key.

If you have been granted access to an API key, you can generate the key by navigating to your account security settings here.

Xeneta expects the API key string to be included in all API requests to the server in the header.

api_key: "test_flKdjskflsDsf43534dfsf"

Requests

List all corridors

The GET request returns JSON structured like this:


{
    "success": true,
    "corridors": [
        {
            "origin": {
                "slug": "west_africa",
                "name": "West Africa"
            },
            "destination": {
                "slug": "north_africa_mediterranean",
                "name": "North Africa Mediterranean"
            }
        },
        {
            "origin": {
                "slug": "west_africa",
                "name": "West Africa"
            },
            "destination": {
                "slug": "indian_ocean_islands_ioi",
                "name": "Indian Ocean Islands (IOI)"
            }
        },
        [...]
    ]
}

This endpoint retrieves a list of all available corridors. No additional parameters are required.

HTTP Request

GET https://api.xeneta.com/v1/corridors

List all regions

The GET request returns JSON structured like this:


{
    "success": true,
    "regionChildren": {
        "adriatic_ionian": [
            {
                "name": "Italy East",
                "slug": "italy_east"
            },
            {
                "name": "Adriatic East",
                "slug": "adriatic_east"
            }
        ],
        "africa": [
            {
                "name": "East Africa",
                "slug": "east_africa"
            },
            {
                "name": "North Africa Mediterranean",
                "slug": "north_africa_mediterranean"
            },
            {
                "name": "South Africa",
                "slug": "south_africa"
            },
            {
                "name": "Indian Ocean Islands (IOI)",
                "slug": "indian_ocean_islands_ioi"
            },
            {
                "name": "West Africa",
                "slug": "west_africa"
            }
        ],
        "world": [
              {
                "name": "Oceania",
                "slug": "oceania"
              },
              {
                "name": "Latin America",
                "slug": "latin_america"
              },
              {
                "name": "Europe",
                "slug": "europe"
              },
              {
                "name": "Middle East",
                "slug": "middle_east"
              },
              {
                "name": "Asia",
                "slug": "asia"
              },
              {
                "name": "North America",
                "slug": "north_america"
              },
              {
                "name": "Africa",
                "slug": "africa"
              }
          ],
        [...]
    }
}

This endpoint retrieves a list of all regions and their sub-level regions. Only regions containing sub-regions appear in the response. No input parameters are required for the request.

This request is useful for determining the parent-child relationship between regions and sub-regions. For example, if you’d like to find the parent region of the adriatic_east sub-region, you can use the results of this request to determine that it falls under the adriatic_ionian region.

HTTP Request

GET https://api.xeneta.com/v1/regions

Request Specific Corridors

Request body:


{
    "origin": "china_main",
    "destination": "north_europe_main",
    "equipmentType": "20dc",
    "contractLength": "combined",
    "date": "2016-09-01",
    "includeRegionValues": false
}

Response body:

{
    "success": true,
    "prices": [
        {
            "origin": "CNSGH",
            "destination": "NOOSL",
            "equipmentType": "20dc",
            "contractLength": "combined",
            "date": "2016-09-01",
            "values": {
                "dataQuality": "10+",
                "quant2.5": 210,
                "quant25": 374,
                "quant75": 654,
                "quant97.5": 964,
                "mean": 485,
                "median": 587
            }
        },
        {
            "origin": "CNSGH",
            "destination": "DEHAM",
            "equipmentType": "20dc",
            "contractLength": "combined",
            "date": "2016-09-01",
            "values": {
                "dataQuality": "100+",
                "quant2.5": 510,
                "quant25": 774,
                "quant75": 1154,
                "quant97.5": 1464,
                "mean": 985,
                "median": 987
            }
        },
        [...]
    ]
}

This endpoint retrieves specific corridor details by submitting a region-to-region price query. Each port-to-port combination found within the queried origin and destination regions will appear in the response. As seen in the example request, price details for “CNSGH” to “NOOSL” could appear when querying china_main to north_europe_main because the port combination is contained within those two regions.

HTTP Request

POST https://api.xeneta.com/v1/corridors/prices

Request Parameters

Requests should be sent as JSON objects containing the query parameters as attribute value pairs. The header should specify that a JSON object is being sent and the Content-Type header should be set to application/json.

Parameter Description Accepted Values Type
origin The corridor’s origin region. region slug string
destination The corridor’s destination region. region slug string
equipmentType The equipment type requested. 20DC, 40DC, 40HC, 20RE, 40RH, 20TK, all string
contractLength The contract length requested. short, long, and combined (see table below for definitions and usage) string
date The date on which the aggregation is valid. Default value is today’s date (YYYY-mm-dd) string
includeRegionValues Optional Parameter for including pricing information at a regional level. Default value is false. true, false boolean
thcType
Optional
Parameter that specifies the terminal handling methodology (THC) to be included in the price results. If no specific parameter is selected, the corridor’s standard THC methodology will be applied. More information on corridor THC methodology can be found here. othc (origin THC only), dthc (destination THC only), both (all THC included), meth (use corridor’s standard methodology), none (no THC included) string
contractedWithin Optional Parameter that specifies the date range the contract was initiated. If this parameter is not specified, the default value is all. 3months (within past 3 months), 6months (within past 6 months), all (within any length of time) string
Contract Type Length
short <32 days
long >88 days
combined The arithmetic average of all available contract lengths combined

Response Parameters

Parameter Description Type
origin The UNLOC of the origin port. string
destination The UNLOC of the destination port. string
equipmentType The equipment type. This is identical to the equipment type requested, or in the case of an “all” request, all the equipment types will be returned. This means all equipment type objects being returned for each port-to-port combination (if enough data is available for all equipment types). string
contractLength This is the contractLength type. In the case of a “combined” contract length, an arithmetic average value for all the contract lengths will be returned. string
date The date on which the aggregation is valid (YYYY-mm-dd). string
values A list element containing the actual Xeneta prices, as well as data quality information. See values table below

values element contents

The values element in the JSON response contains an array of pricing components. Below is a description of each component in the values array. All figures are integers and are expressed in USD.

Parameter Description Type
dataQuality This value shows the number of contracts that are used to calculate the displayed prices. More specifically the possible values expressed as a string are: “<10”, “10+”, “30+”, “100+”, and “1000+” string
quant2.5 The 2.5th percentile point price number
quant25 The 25th percentile point price number
quant75 The 75th percentile point price number
quant97.5 The 97.5th percentile point price number
mean The calculated arithmetic mean number
median The median figure of price information number

Response when includeRegionValues is set to true

When the optional includeRegionValues is set to true, the response will contain additional keys: regionValues, originRegion, originRegionName, destinationRegion, and destinationRegionName.

regionValues provides the regional price figures, whereas originRegion and destinationRegion indicate the origin and destination region. The originRegionName and destinationRegionName fields provide the standard text names.

Example of response when includeRegionValues is set to true

{
    "success": true,
    "prices": [
        {
            "values": {
                "quant97.5": 2197,
                "quant75": 1474,
                "quant25": 827,
                "quant2.5": 516,
                "median": 1198,
                "mean": 1204,
                "dataQuality": "10+"
            },
            "regionValues": {
                "quant97.5": 2272,
                "quant75": 1472,
                "quant25": 850,
                "quant2.5": 250,
                "median": 1192,
                "mean": 1197,
                "dataQuality": "100+"
            },
            "originRegion": "china_east_main",
            "originRegionName": "China East Main",
            "origin": "CNXAM",
            "equipmentType": "40DC",
            "destinationRegion": "adriatic_east",
            "destinationRegionName": "Adriatic East",
            "destination": "SIKOP",
            "date": "2016-03-10",
            "contractLength": "combined"
        },
        [...]
    ]
}

Requesting Corridor Aggregates

For querying corridor-level (region-to-region) aggregate values. The date-range can be specified in order to update higher-level aggregated values. As shown in the example request, china_main to north_europe_main would be consider a corridor-level origin and destination combination.

HTTP Request

POST https://api.xeneta.com/v1/corridors/aggregates

Request Parameters

Parameter Description Accepted Values Type
origin The origin slug of the corridor. region slug string
destination The destination slug of the corridor. region slug string
fromDate Beginning of date range. YYYY-mm-dd string
toDate End of date range. YYYY-mm-dd string
thcType Optional Parameter that specifies the terminal handling charge (THC) methodology to include in the price results. If no specific parameter is selected, the corridor’s standard THC methodology will be applied. More information on corridor THC methodology can be found here. othc (origin THC only), dthc (destination THC only), both (all THC included), meth (use corridor’s standard methodology), none (no THC included) string

Request body:


{
    "origin": "china_main",
    "destination": "north_europe_main",
    "fromDate": "2016-09-01",
    "toDate": "2016-09-02",
    "thcType": "othc"
}

Response body:


{
    "success": true,
    "aggregates": [
        {
            "equipmentType":"20DC",
            "contractLength":"short",
            "values":[
                {
                    "date":"2016-09-01",
                    "dataQuality":"100+",
                    "quant2.5":210,
                    "quant25":374,
                    "quant75":662,
                    "quant97.5":964,
                    "mean":485,
                    "median": 586

                },
                {
                    "date":"2016-09-02",
                    "dataQuality":"100+",
                    "quant2.5":212,
                    "quant25":376,
                    "quant75":662,
                    "quant97.5":966,
                    "mean":487,
                    "median": 580
                }
            ]
        },
        {
            "equipmentType":"40DC",
            "contractLength":"short",
            "values":[
                {
                    "date":"2016-09-01",
                    "dataQuality":"100+",
                    "quant2.5":500,
                    "quant25":764,
                    "quant75":1121,
                    "quant97.5":1444,
                    "mean":965,
                    "median": 972
                },
                {
                    "date":"2016-09-02",
                    "dataQuality":"100+",
                    "quant2.5":512,
                    "quant25":776,
                    "quant75":1232,
                    "quant97.5":1466,
                    "mean":987,
                    "median": 989
                }
            ]    
        },
        {
            "equipmentType":"40HC",
            "contractLength":"short",
            "values":[
                {
                    "date":"2016-09-01",
                    "dataQuality":"100+",
                    "quant2.5":510,
                    "quant25":774,
                    "quant75":1131,
                    "quant97.5":1464,
                    "mean":985,
                    "median": 980
                },
                {
                    "date":"2016-09-02",
                    "dataQuality":"100+",
                    "quant2.5":522,
                    "quant25":786,
                    "quant75":1242,
                    "quant97.5":1486,
                    "mean":987,
                    "median": 1004
                }
            ]    
        },
        [...]
    ]
}

Xeneta monitors THCs and includes them on the various routes, depending on the standard methodology. The description of said methodology is static and is published here.

Response Parameters

The response is a JSON list containing the equipment type, contract length, and aggregated value price array (updated once per day).

The equipmentType and contractLength combinations returned in the query affect the results of each individual daily values array returned by the query. Some combinations may return more results than others.

Parameter Description Type
equipmentType The equipment type contained within the response. The returned values can be “20DC”, “40DC”, “20RE”, “40RH”, “20TK” and “40HC”. string
contractLength The contractLength type contained within the response. The returned values can be “short” or “long”. string
values A list element containing the actual Xeneta prices, as well as data quality information per each day contained within the data range of the query see table below

values element contents

The response is a JSON list containing objects with the equipment type, contract length, and aggregated value price array (updated once per day). All figures are integers and are expressed in USD.

Note: The values object array’s content is dependent upon on the amount of price datapoints returned by the aggregates query. If the query returns less than two datapoints for a specific day within the queried date range, the values object may contain null values due to limited datapoints.

Parameter Description Type
date The date on which the aggregation is valid. (YYYY-mm-dd) string
dataQuality This value shows the number of contracts that are used to calculate the displayed prices. More specifically the possible values expressed as a string are: “<10”, “10+”, “30+”, “100+”, and “1000+” string
quant2.5 The 2.5th percentile point price number
quant25 The 25th percentile point price number
quant75 The 75th percentile point price number
quant97.5 The 97.5th percentile point price number
mean The calculated arithmetic mean number
median The median figure of price information number

Requesting Lane Aggregates

For querying port-to-port level aggregate values. Date-range can be specified in order to update higher-level aggregated values. Please note that the date range requested must not exceed 31 days.

HTTP Request

POST https://api.xeneta.com/v1/lanes/aggregates

Request Parameters

Parameter Description Type
origin 5-character UN/LOCODE origin port code string
destination 5-character UN/LOCODE destination port code string
fromDate Beginning of date range (YYYY-mm-dd) string
toDate End of date range (YYYY-mm-dd) string

Request body:


{
    "origin": "CNSGH",
    "destination": "NOOSL",
    "fromDate": "2017-09-01",
    "toDate": "2017-09-02"
}

Response body:


{
    "aggregates": [
        {
            "contractLength": "long",
            "equipmentType": "20DC",
            "values": [
                {
                    "dataQuality": "10+",
                    "date": "2017-09-01",
                    "mean": 1003,
                    "median": 1027,
                    "quant2.5": 624,
                    "quant25": 914,
                    "quant75": 1164,
                    "quant97.5": 1222
                },
                {
                    "dataQuality": "10+",
                    "date": "2017-09-02",
                    "mean": 1003,
                    "median": 1027,
                    "quant2.5": 624,
                    "quant25": 914,
                    "quant75": 1164,
                    "quant97.5": 1222
                }
            ]
        },
        {
            "contractLength": "short",
            "equipmentType": "20DC",
            "values": [
                {
                    "dataQuality": "30+",
                    "date": "2017-09-01",
                    "mean": 1162,
                    "median": 1103,
                    "quant2.5": 943,
                    "quant25": 1027,
                    "quant75": 1272,
                    "quant97.5": 1580
                },
                {
                    "dataQuality": "30+",
                    "date": "2017-09-02",
                    "mean": 1162,
                    "median": 1103,
                    "quant2.5": 943,
                    "quant25": 1027,
                    "quant75": 1272,
                    "quant97.5": 1580
                }
            ]
        },
        {
            "contractLength": "long",
            "equipmentType": "40DC",
            "values": [
                {
                    "dataQuality": "10+",
                    "date": "2017-09-01",
                    "mean": 1766,
                    "median": 1768,
                    "quant2.5": 1187,
                    "quant25": 1647,
                    "quant75": 1916,
                    "quant97.5": 2292
                },
                {
                    "dataQuality": "10+",
                    "date": "2017-09-02",
                    "mean": 1766,
                    "median": 1768,
                    "quant2.5": 1187,
                    "quant25": 1647,
                    "quant75": 1916,
                    "quant97.5": 2292
                }
            ]
        },
        [...]
    ]
}

Xeneta monitors THCs and includes them on the various routes, depending on the standard methodology. The description of said methodology is static and is published here.

Response Parameters

Parameter Description Type
success If the query has returned a valid data response, the success parameter is returned true boolean
originRegion The slug of the containing region for the queried origin port string
destinationRegion The slug of the containing region for the queried destination port string
aggregates The array containing all equipment types, contract lengths, and prices (values) returned in the query’s response. see table below

aggregates element contents

The aggregates array in the JSON response contains objects with the equipment type, contract length, and aggregated values price array (updated once per day). All figures are integers and are expressed in USD.

Parameter Description Type
equipmentType The equipment type contained within the response. The returned values can be “20DC”, “40DC”, “40HC”, “20RE”, “40RH”, and “20TK”. string
contractLength The contractLength type contained within the response. The returned values can be “short” or “long”. string
values A list element containing the actual Xeneta prices, as well as data quality information per each day contained within the data range of the query see table below

values element contents

The values array in the JSON response contains an array of pricing components. Below is a description of each component in the values array. All figures are integers and are expressed in USD.

Note: The values object array’s content is dependent upon on the amount of price datapoints returned by the aggregates query. If the query returns less than two datapoints for a specific day within the queried date range, the values object may contain null values due to limited datapoints.

Parameter Description Type
date The date on which the aggregation is valid. (YYYY-mm-dd) string
dataQuality This value shows the number of contracts that are used to calculate the displayed prices. More specifically the possible values expressed as a string are: “<10”, “10+”, “30+”, “100+”, and “1000+” string
quant2.5 The 2.5th percentile point price number
quant25 The 25th percentile point price number
quant75 The 75th percentile point price number
quant97.5 The 97.5th percentile point price number
mean The calculated arithmetic mean number
median The median figure of price information number

Requesting Mixed Location Type Aggregates

For querying port-level or region-level aggregate values within a given date range. Only one price per day within the requested date range will be returned and the maximum date range allowed is 31 days. The query can contain a combination of port or regional locations.

HTTP Request

POST https://api.xeneta.com/v1/locations/aggregates

Request Parameters

Parameter Description Type
origin The origin slug (region or port) string
destination The destination slug (region or port) string
fromDate Beginning of date range (YYYY-mm-dd) string
toDate End of date range (YYYY-mm-dd) string
equipmentType The equipment type requested 20DC, 40DC, 40HC, 20RE, 40RH, 20TK
contractLength The contract length requested short, long (see table below for definitions and usage)
Contract Type Length
short <32 days
long >88 days

Request body:


{
  "origin": "CNSGH",
  "destination": "north_america",
  "fromDate": "2017-09-01",
  "toDate": "2017-09-30",
  "equipmentType" : "40DC",
  "contractLength": "long"
}

Response body:


{
    "prices": [
        {
            "dataQuality": "100+",
            "date": "2017-09-01",
            "mean": 1430,
            "median": 1432,
            "quant2.5": 865,
            "quant25": 1300,
            "quant75": 1585,
            "quant97.5": 2075
        },
        {
            "dataQuality": "100+",
            "date": "2017-09-02",
            "mean": 1430,
            "median": 1432,
            "quant2.5": 865,
            "quant25": 1300,
            "quant75": 1585,
            "quant97.5": 2075
        },
        {
            "dataQuality": "100+",
            "date": "2017-09-30",
            "mean": 1447,
            "median": 1443,
            "quant2.5": 965,
            "quant25": 1314,
            "quant75": 1575,
            "quant97.5": 2082
        },        
        [...]
    ],
    "success": true
}

Xeneta monitors THCs and includes them on the various routes, depending on the standard methodology. The description of said methodology is static and is published here.

Response Parameters

The response is a JSON list containing the date, data quality, and aggregated value price array (updated once per day).

The equipmentType and contractLength combinations used in the query affect the results of each individual daily prices array returned by the query. Some combinations may return more results than others.

Parameter Description Type
success If the query has returned a valid data response, the success parameter is returned true boolean
prices An array containing the actual Xeneta prices, as well as data quality information per each day contained within the data range of the query see table below

prices element contents

The response is a JSON list containing objects with the date, data quality, and price values (updated once per day). All figures are integers and are expressed in USD.

Note: The prices object array’s content is dependent upon on the amount of price datapoints returned by the aggregates query. If the query returns less than two datapoints for a specific day within the queried date range, the prices object may contain null values due to limited datapoints.

Parameter Description Type
dataQuality This value shows the number of contracts that are used to calculate the displayed prices. More specifically the possible values expressed as a string are: “<10”, “10+”, “30+”, “100+”, and “1000+” string
date The date on which the aggregation is valid. (YYYY-mm-dd) string
mean The calculated arithmetic mean number
median The median figure of price information number
quant2.5 The 2.5th percentile point price number
quant25 The 25th percentile point price number
quant75 The 75th percentile point price number
quant97.5 The 97.5th percentile point price number

Data Quality

Insufficient Aggregate Data

When there is not enough data available to display requested corridor aggregate prices, the values object’s response content will change. When this occurs, the dataQuality field will return a na (“not applicable”) value and the fields normally containing prices will be returned null.

Normal response:


[...]
{
    "origin": "NLRTM",
    "destination": "NOOSL",
    "equipmentType": "20DC",
    "contractLength": "short",
    "dataQuality": "10+",
    "date": "2017-03-14",
    "values": {
        "quant2.5": 122,
        "quant25": 325,
        "quant75": 775,
        "quant97.5": 978,
        "mean": 550,
        "median": 534
    }
}
[...]

Insufficient aggregate data response:

[...]
{
    "origin": "NLRTM",
    "destination": "NOBGO",
    "equipmentType": "40HC",
    "contractLength": "short",
    "dataQuality": "na",
    "date": "2017-03-14",
    "values": {
        "quant2.5": null,
        "quant25": null,
        "quant75": null,
        "quant97.5": null,
        "mean": null,
        "median": null
    }
}
[...]