Administration

The Administration Service offers a usage feature making it possible to follow the API usage per month.

Administration have the following endpoints:

1. GET /administration/usage
2. GET /administration/usage/credits

GET /administration/usage

A description of the input parameters, example input, HTTP return codes and response are available in Swagger GET /administration/usage

For further explanation of the fields see the Models section of the Swagger documentation.

The ‘text’ field from Usage output contains the following strings:

• “Bill of lading number transports’ container count”
  • Refers to the amount of Containers associated with initiated B/L transports
• “Carrier booking reference transports’ container count”
  • Refers to the amount of Containers associated with initiated booking number transports
• “Equipment reference transports’ container count”
  • Refers to the amount of Container Transports initiated using Container-ID
• “Bill of lading number transports”
  • Refers to the amount of initiated BL transports
• “Carrier booking reference transports”
  • Refers to the amount of initiated booking number transports
• “Equipment reference transports with vessel_operator_carrier_code”
  • Refers to the amount of Container Transports initiated with SCAC
• “Equipment reference transports without vessel_operator_carrier_code”
  • Refers to the amount of Container Transports initiated without SCAC

The ‘endpoint’ field from usage output contains the following strings:

• used endpoint ex. /api/ports/{un_location_code}/port-congestions/statistics
• “Total container count”
  • Refers to the total amount of containers tracked across all identifiers

Please note:

• Full correct usage is calculated from December 2022 and the usage endpoint is available for testing from November 2022.
• If an endpoint is not called during a month, it will not be present in usage output
• usage is updated every quarter

Code Example:

import json
import requests
request_data = {"user_id": "username", "password": "passWORD1234##"}
data_json = json.dumps(request_data)
response_auth = requests.post(
    "https://api-demo.oceanio.com/authentication/login",
    headers={
        "content-type": "application/json",
        "X-Api-Key": "LVQEGHrM0P5CceeUbGWSO5gX0kZlOG877Kr.....",
    },
    data=data_json,
)
result = json.loads(response_auth.content)
response = requests.get(
    "https://api-demo.oceanio.com/administration/usage?year=2022&month=11&page=1&page_size=10",
    headers={
        "content-type": "application/json",
        "X-Api-Key": "LVQEGHrM0P5CceeUbGWSO5gX0kZlOG877Kr.....",
        "Authorization": f"Bearer {result.get('token')}",
    },
)
print(json.loads(response.content))

Sample output:

"last_updated_datetime": "2022-11-17T13:00:25.319935+00:00",

    "usage": [

        {
            "user_id": null,
            "usage_year": 2022,
            "usage_month": 11,
            "usage_type": "PUSH",
            "usage_method": null,
            "endpoint": "Container with data count",
            "status": "SUCCESS",
            "unit": "REQUESTS",
            "usage_count": 2,
            "text": "Bill of lading number transports' container count"
        },

        {
            "user_id": null,
            "usage_year": 2022,
            "usage_month": 11,
            "usage_type": "PUSH",
            "usage_method": null,
            "endpoint": "Total container count",
            "status": "SUCCESS",
            "unit": "CONTAINERS",
            "usage_count": 3,
            "text": null
        },

        {
            "user_id": "kib",
            "usage_year": 2022,
            "usage_month": 11,
            "usage_type": "REQUEST",
            "usage_method": "GET",
            "endpoint": "/api/ports/port-congestions/statistics",
            "status": "ERROR",
            "unit": "REQUESTS",
            "usage_count": 2,
            "text": null
        },

        {
            "user_id": "kib",
            "usage_year": 2022,
            "usage_month": 11,
            "usage_type": "REQUEST",
            "usage_method": "POST",
            "endpoint": "/api/transports",
            "status": "SUCCESS",
            "unit": "REQUESTS",
            "usage_count": 1,
            "text": "Carrier booking reference transports"
        },

        {
            "user_id": "kib",
            "usage_year": 2022,
            "usage_month": 11,
            "usage_type": "REQUEST",
            "usage_method": "GET",
            "endpoint": "/api/ports/{un_location_code}/port-congestions/statistics",
            "status": "SUCCESS",
            "unit": "REQUESTS",
            "usage_count": 3,
            "text": null

        },

        {

            "user_id": "kib",
            "usage_year": 2022,
            "usage_month": 11,
            "usage_type": "REQUEST",
            "usage_method": "GET",
            "endpoint": "/api/ports/port-congestions",
            "status": "SUCCESS",
            "unit": "REQUESTS",
            "usage_count": 5,
            "text": null

        },

        {

            "user_id": "kib",
            "usage_year": 2022,
            "usage_month": 11,
            "usage_type": "REQUEST",
            "usage_method": "POST",
            "endpoint": "/api/transports",
            "status": "SUCCESS",
            "unit": "REQUESTS",
            "usage_count": 2,
            "text": "Bill of lading number transports"

        },

        {

            "user_id": "kib",
            "usage_year": 2022,
            "usage_month": 11,
            "usage_type": "REQUEST",
            "usage_method": "GET",
            "endpoint": "/api/port-intelligence/dwell",
            "status": "SUCCESS",
            "unit": "REQUESTS",
            "usage_count": 1,
            "text": null

        },

        {

            "user_id": null,
            "usage_year": 2022,
            "usage_month": 11,
            "usage_type": "PUSH",
            "usage_method": null,
            "endpoint": "Container with data count",
            "status": "SUCCESS",
            "unit": "REQUESTS",
            "usage_count": 1,
            "text": "Equipment reference transports' container count"

        },

        {
            "user_id": "kib",
            "usage_year": 2022,
            "usage_month": 11,
            "usage_type": "REQUEST",
            "usage_method": "POST",
            "endpoint": "/api/transports",
            "status": "ERROR",
            "unit": "REQUESTS",
            "usage_count": 11,
            "text": null
        }

    ]

}

GET /administration/usage/credits

The credits endpoint provides an accumulation of the credit usage per service.

Please note:

This credit endpoint statement is only to be considered as an indicative calculation of a customer’s consumption of credits at a given time.

In case of disputes, questions etc. regarding a customer’s consumption of credits on the basis of this credit endpoint statement, invoices issued for a given period to the customer will be valid rather than this statement.

This may, for example, apply in cases where several companies belonging to the same group are settled as one and the same company, but have been created as multiple companies in the OceanIO system.

Code Example

import json
import requests


request_data = {“user_id”: “USERNAME”, 
                “password”: “PASSWORD!123”}

data_json = json.dumps(request_data)

response_auth = requests.post(
    “https://api-demo.oceanio.com/authentication/login”,
    headers={
        ‘content-type’: “application/json”,
        ‘x-api-key’: “XXXXXXXXXXXXXXXXXXXX”,
        ‘Content-Type’: ‘application/json’
             },
    data=data_json)

result = json.loads(response_auth.content)

response = requests.get(
    “https://api-demo.oceanio.com/administration/usage/credits?page=1&page_size=10”,
    headers={
        “content-type”: “application/json”, 
        ‘X-Api-Key’: “XXXXXXXXXXXXXXXXXXXX”,
        “Authorization”: f”Bearer {result.get(‘token’)}“})

print(json.loads(response.content))

Sample Output:

{
  "total_credit_used": 5.0,
  "usage": [
    {
      "title": "port_intelligence_anchorage_and_berthing_by_ports",
      "usage": 4,
      "credits": 1
    },
    {
      "title": "container_tracks",
      "usage": 2,
      "credits": 4
    }
  ]
}