BlueX Open Freight Marketplace (OFM) API

Introduction

This BlueX Open Freight Marketplace (OFM) API document explains the various product offerings from Evergreen's GreenX platform through API integrations. The API supports carrier port pairs, schedules, and spot rates, and enables users to search for rates and book through GreenX seamlessly via a Deep Link provided by the API.

The API currently supports only Evergreen’s GreenX platform, and we are actively working on supporting further carrier API integrations, along with more new features, such as inventory management, instant booking, and many more.

BlueX presents data via a REST API using JSON serialization and is protected with JWT. To access the API, please first click "Getting Started" to get onboarded and collect your API key.

All BlueX API requests are sent to https://api.bluextrade.com.

Getting Started

Before using the BlueX OFM API, please first register as a developer on our registration page. The BlueX team will review your application, and once your registration is confirmed, you will receive an API key and onboarding information for your developers.

API Security Model

Our API is accessible over HTTPs and returns JSON responses, and can only be accessed through BlueX provided API keys and tokens. When customers or third-party service providers access the BlueX OFM services via APIs, they are required to provide their API keys during the onboarding process.

API Key

Before accessing API, the client must have an API key. The API key is obtained offline. It identifies who is the client.

Token

The client calls HTTP GET /v1/auth?api-key=[api key]&referral-user=[referral user] with a valid API key and a referral user string. The referral user is a string can identify the user who invoke /v1/auth/ with the API key. Both the api-key and referral-user are required. /v1/auth will return a JSON response. The token is in the "token" field of the response. This is an example of the response.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlIjp7ImNvbXBhbnkiOiJTYW5kYm94IHRlc3QgY29tcGFueSJ9LCJwb2xpY3kiOlt7InNlcnZpY2UiOiJzY2hlZHVsZSIsImFsbG93Ijp0cnVlfV0sImV4cGlyZWRfYXQiOjE1ODQwMDY0NzF9.TaRCEr9p88s_oxUxsxJ6-K2ccrMnzLhKR2W0ossH6uE"
}

The token is a JWT token. To access all APIs (except /v1/auth), the client must put the token in the HTTP header. Here is an example.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlIjp7ImNvbXBhbnkiOiJTYW5kYm94IHRlc3QgY29tcGFueSJ9LCJwb2xpY3kiOlt7InNlcnZpY2UiOiJzY2hlZHVsZSIsImFsbG93Ijp0cnVlfV0sImV4cGlyZWRfYXQiOjE1ODQwMDY0NzF9.TaRCEr9p88s_oxUxsxJ6-K2ccrMnzLhKR2W0ossH6uE

The system will verify if the token is issued by the system or if the token is expired. The client request will be rejected if the token not passed the verification process.

Token Refresh

The tokens issued by the system will be expired automatically. A token will expire one day after it is issued. The client can obtain new token by calling /v1/auth with the API key or calling HTTP GET /v1/refresh_token. The response of /v1/refresh_token is the same as /v1/auth.

Authentication

To authenticate in the JWT bearer flow, you will need to obtain a JWT containing data on the authentication request, before exchanging it for an access token.

Get a new access token

query Parameters
api-key
required
string
referral-user
required
string

Responses

202

Accepted

403

Forbidden

404

Not Found

get /v1/auth
https://api.bluextrade.com/v1/auth

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Refresh the access token

Authorizations:

Responses

202

Accepted

get /v1/refresh_token
https://api.bluextrade.com/v1/refresh_token

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Rates

The "Rates" API supports features for customers to receive container information and spot rates. Customers can also receive information from GreenX about service routes, vessel/voyage, and container types.

List available rates

List available rates on GreenX

Authorizations:
query Parameters
scac
required
string

The brand SCAC code of the carrier to list rates for, eg. EGLV for Evergreen Marine Corp.

por
required
string

Set to filter results to match UN/LOCODE of origin location.

fnd
required
string

Set to filter results to match UN/LOCODE of destination location.

departureFrom
required
string

Earliest departure date for requested rates in ISO Date Format 'yyyy-MM-dd', eg. 2020-01-23

departureTo
string

Latest departure date for requested rates in ISO Date Format 'yyyy-MM-dd’, eg. 2020-02-14

containers
Array of strings
Example: containers=2x20SD&containers=3x40HQ

Container amounts and types for the request.

commodities
Array of strings
Example: commodities=GDSM

Commodity Code of the content in the containers

porServiceMode
string

Specify service mode for origin, Merchant haulage (CY) or Carrier haulage (SD)

fndServiceMode
string

Specify service mode for destination, Merchant haulage (CY) or Carrier haulage (SD)

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get /v1/rates
https://api.bluextrade.com/v1/rates

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error":
    {
    • "code": "string",
    • "message": "string"
    },
  • "offers":
    [
    • {
      • "id": "37b5e0ee-badb-4340-a7ba-dde0a85b5954",
      • "brandScac": "EGLV",
      • "productCode": "SC2020XYZ",
      • "price":
        {
        • "containerPrices":
          [
          • {
            • "containerType": "20SD",
            • "bas":
              {
              • "currency": "USD",
              • "rate": 1200,
              • "qty": 2,
              • "amount": 2400,
              • "rateBasis": "PER_CONTAINER",
              • "rateType": "PAID_WITH_FREIGHT",
              • "chargeCode": "BAS",
              • "chargeDescription": "Basic Ocean Freight"
              },
            • "surcharges":
              [
              • {
                • "currency": "USD",
                • "rate": 1200,
                • "qty": 2,
                • "amount": 2400,
                • "rateBasis": "PER_CONTAINER",
                • "rateType": "PAID_WITH_FREIGHT",
                • "chargeCode": "BAS",
                • "chargeDescription": "Basic Ocean Freight"
                }
              ]
            }
          ],
        • "surcharges":
          [
          • {
            • "currency": "USD",
            • "rate": 1200,
            • "qty": 2,
            • "amount": 2400,
            • "rateBasis": "PER_CONTAINER",
            • "rateType": "PAID_WITH_FREIGHT",
            • "chargeCode": "BAS",
            • "chargeDescription": "Basic Ocean Freight"
            }
          ],
        • "annotation":
          {
          • "demurrage": "Per Tariff",
          • "detention": "Per Tariff",
          • "included": "THC/L;THC/D; PSS; BAC; 1st set B/L fee",
          • "subjectTo": "Local charge"
          },
        • "totalPrice": 4436
        },
      • "schedule":
        {
        • "id": "5e751754-ecc1-4412-a818-82a2811159b0",
        • "brandScac": "EGLV",
        • "from":
          {
          • "location":
            {
            • "id": "string",
            • "scac": "EGLV",
            • "unlocode": "MXMEX",
            • "name": "Mexico City",
            • "fullName": "Mexico City, Distrito Federal, Mexico",
            • "countryCode": "MX",
            • "countryName": "Mexico",
            • "timezone": "America/Mexico_City",
            • "geo":
              {
              • "latitude": -991332080,
              • "longitude": 194326080
              }
            },
          • "eta": 0,
          • "etd": 0,
          • "cutOffDate": 0
          },
        • "to":
          {
          • "location":
            {
            • "id": "string",
            • "scac": "EGLV",
            • "unlocode": "MXMEX",
            • "name": "Mexico City",
            • "fullName": "Mexico City, Distrito Federal, Mexico",
            • "countryCode": "MX",
            • "countryName": "Mexico",
            • "timezone": "America/Mexico_City",
            • "geo":
              {
              • "latitude": -991332080,
              • "longitude": 194326080
              }
            },
          • "eta": 0,
          • "etd": 0,
          • "cutOffDate": 0
          },
        • "firstLoadingPort":
          {
          • "location":
            {
            • "id": "string",
            • "scac": "EGLV",
            • "unlocode": "MXMEX",
            • "name": "Mexico City",
            • "fullName": "Mexico City, Distrito Federal, Mexico",
            • "countryCode": "MX",
            • "countryName": "Mexico",
            • "timezone": "America/Mexico_City",
            • "geo":
              {
              • "latitude": -991332080,
              • "longitude": 194326080
              }
            },
          • "eta": 0,
          • "etd": 0,
          • "cutOffDate": 0
          },
        • "lastDischargePort":
          {
          • "location":
            {
            • "id": "string",
            • "scac": "EGLV",
            • "unlocode": "MXMEX",
            • "name": "Mexico City",
            • "fullName": "Mexico City, Distrito Federal, Mexico",
            • "countryCode": "MX",
            • "countryName": "Mexico",
            • "timezone": "America/Mexico_City",
            • "geo":
              {
              • "latitude": -991332080,
              • "longitude": 194326080
              }
            },
          • "eta": 0,
          • "etd": 0,
          • "cutOffDate": 0
          },
        • "vessel":
          {
          • "name": "EVER LINKING"
          },
        • "voyageNumber": "0907-034E",
        • "legs":
          [
          • {
            • "from":
              {
              • "location":
                {
                • "id": "string",
                • "scac": "EGLV",
                • "unlocode": "MXMEX",
                • "name": "Mexico City",
                • "fullName": "Mexico City, Distrito Federal, Mexico",
                • "countryCode": "MX",
                • "countryName": "Mexico",
                • "timezone": "America/Mexico_City",
                • "geo":
                  {
                  • "latitude": -991332080,
                  • "longitude": 194326080
                  }
                },
              • "eta": 0,
              • "etd": 0,
              • "cutOffDate": 0
              },
            • "to":
              {
              • "location":
                {
                • "id": "string",
                • "scac": "EGLV",
                • "unlocode": "MXMEX",
                • "name": "Mexico City",
                • "fullName": "Mexico City, Distrito Federal, Mexico",
                • "countryCode": "MX",
                • "countryName": "Mexico",
                • "timezone": "America/Mexico_City",
                • "geo":
                  {
                  • "latitude": -991332080,
                  • "longitude": 194326080
                  }
                },
              • "eta": 0,
              • "etd": 0,
              • "cutOffDate": 0
              },
            • "transportMode": "VESSEL",
            • "tradeLane": "WSA4",
            • "vessel":
              {
              • "name": "EVER LINKING"
              },
            • "voyageNumber": "0907-034E",
            • "transitTime": 19
            }
          ]
        },
      • "inventory":
        {
        • "bookingClosingDate": "1586707200",
        • "ct20Available": "100",
        • "ct40Available": "109",
        • "ct45Available": "83"
        },
      }
    ]
}

List supported containers

List supported containers on GreenX

Authorizations:

Responses

200

OK

401

Unauthorized

403

Forbidden

get /v1/rates/containers
https://api.bluextrade.com/v1/rates/containers

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error":
    {
    • "code": "string",
    • "message": "string"
    },
  • "containers":
    [
    • {
      • "id": "20SD",
      • "name": "20DRY",
      • "iso": "22G1",
      • "type": "DRY",
      • "label": "20' Dry Standard",
      • "cargoType": "DRY",
      • "size": "20",
      • "height": "8 6",
      • "reefer": "false"
      }
    ]
}

Schedules

The "Schedules" API provides information about routes and schedules on end-to-end searches, which includes vessel/voyage, service routes, POR, POL, POD and PDL, ETA, ETD, and transit times.

List schedules

List all the schedules on GreenX

Authorizations:
query Parameters
scac
required
string

The brand SCAC code of the carrier to list rates for, eg. EGLV for Evergreen Marine Corp.

por
required
string

Set to filter results to match UN/LOCODE of origin location.

fnd
required
string

Set to filter results to match UN/LOCODE of destination location.

departureFrom
required
string

Earliest departure date for requested rates in ISO Date Format 'yyyy-MM-dd', eg. 2020-01-23

departureTo
string

Latest departure date for requested rates in ISO Date Format 'yyyy-MM-dd’, eg. 2020-02-14

Responses

200

OK

401

Unauthorized

403

Forbidden

get /v2/schedules
https://api.bluextrade.com/v2/schedules

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error":
    {
    • "code": "string",
    • "message": "string"
    },
  • "schedules":
    [
    • {
      • "id": "5e751754-ecc1-4412-a818-82a2811159b0",
      • "brandScac": "EGLV",
      • "from":
        {
        • "location":
          {
          • "id": "string",
          • "scac": "EGLV",
          • "unlocode": "MXMEX",
          • "name": "Mexico City",
          • "fullName": "Mexico City, Distrito Federal, Mexico",
          • "countryCode": "MX",
          • "countryName": "Mexico",
          • "timezone": "America/Mexico_City",
          • "geo":
            {
            • "latitude": -991332080,
            • "longitude": 194326080
            }
          },
        • "eta": 0,
        • "etd": 0,
        • "cutOffDate": 0
        },
      • "to":
        {
        • "location":
          {
          • "id": "string",
          • "scac": "EGLV",
          • "unlocode": "MXMEX",
          • "name": "Mexico City",
          • "fullName": "Mexico City, Distrito Federal, Mexico",
          • "countryCode": "MX",
          • "countryName": "Mexico",
          • "timezone": "America/Mexico_City",
          • "geo":
            {
            • "latitude": -991332080,
            • "longitude": 194326080
            }
          },
        • "eta": 0,
        • "etd": 0,
        • "cutOffDate": 0
        },
      • "firstLoadingPort":
        {
        • "location":
          {
          • "id": "string",
          • "scac": "EGLV",
          • "unlocode": "MXMEX",
          • "name": "Mexico City",
          • "fullName": "Mexico City, Distrito Federal, Mexico",
          • "countryCode": "MX",
          • "countryName": "Mexico",
          • "timezone": "America/Mexico_City",
          • "geo":
            {
            • "latitude": -991332080,
            • "longitude": 194326080
            }
          },
        • "eta": 0,
        • "etd": 0,
        • "cutOffDate": 0
        },
      • "lastDischargePort":
        {
        • "location":
          {
          • "id": "string",
          • "scac": "EGLV",
          • "unlocode": "MXMEX",
          • "name": "Mexico City",
          • "fullName": "Mexico City, Distrito Federal, Mexico",
          • "countryCode": "MX",
          • "countryName": "Mexico",
          • "timezone": "America/Mexico_City",
          • "geo":
            {
            • "latitude": -991332080,
            • "longitude": 194326080
            }
          },
        • "eta": 0,
        • "etd": 0,
        • "cutOffDate": 0
        },
      • "vessel":
        {
        • "name": "EVER LINKING"
        },
      • "voyageNumber": "0907-034E",
      • "legs":
        [
        • {
          • "from":
            {
            • "location":
              {
              • "id": "string",
              • "scac": "EGLV",
              • "unlocode": "MXMEX",
              • "name": "Mexico City",
              • "fullName": "Mexico City, Distrito Federal, Mexico",
              • "countryCode": "MX",
              • "countryName": "Mexico",
              • "timezone": "America/Mexico_City",
              • "geo":
                {
                • "latitude": -991332080,
                • "longitude": 194326080
                }
              },
            • "eta": 0,
            • "etd": 0,
            • "cutOffDate": 0
            },
          • "to":
            {
            • "location":
              {
              • "id": "string",
              • "scac": "EGLV",
              • "unlocode": "MXMEX",
              • "name": "Mexico City",
              • "fullName": "Mexico City, Distrito Federal, Mexico",
              • "countryCode": "MX",
              • "countryName": "Mexico",
              • "timezone": "America/Mexico_City",
              • "geo":
                {
                • "latitude": -991332080,
                • "longitude": 194326080
                }
              },
            • "eta": 0,
            • "etd": 0,
            • "cutOffDate": 0
            },
          • "transportMode": "VESSEL",
          • "tradeLane": "WSA4",
          • "vessel":
            {
            • "name": "EVER LINKING"
            },
          • "voyageNumber": "0907-034E",
          • "transitTime": 19
          }
        ]
      }
    ]
}

Locations

The "Locations" API provides information on which supported origin and destination ports offer spot rates on GreenX. Other information includes port codes, city names, countries, and geolocation

List origin ports

List available origin locations for available rates on GreenX

Authorizations:
query Parameters
scac
string

The brand SCAC code of the carrier to list rates for, eg. EGLV for Evergreen Marine Corp.

unlocode
string

Set to filter results to match UN/LOCODE of origin location.

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get /v1/locations/origins
https://api.bluextrade.com/v1/locations/origins

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error":
    {
    • "code": "string",
    • "message": "string"
    },
  • "locations":
    [
    • {
      • "id": "string",
      • "scac": "EGLV",
      • "unlocode": "MXMEX",
      • "name": "Mexico City",
      • "fullName": "Mexico City, Distrito Federal, Mexico",
      • "countryCode": "MX",
      • "countryName": "Mexico",
      • "timezone": "America/Mexico_City",
      • "geo":
        {
        • "latitude": -991332080,
        • "longitude": 194326080
        }
      }
    ]
}

List destination ports

List available destination locations for available rates on GreenX

Authorizations:
query Parameters
scac
string

The brand SCAC code of the carrier to list rates for, eg. EGLV for Evergreen Marine Corp.

unlocode
string

Set to filter results to match UN/LOCODE of destination location.

Responses

200

OK

401

Unautho