Kuehne+Nagel GPS Tracking API

openapi: 3.2.0
info:
  title: IntermodalTransportExecution GPS Tracking API
  description: 'This API enables Intermodal subcontractors who transport containers via truck, rail, and barge for Kuehne+Nagel to receive details about assigned consignments, including job details and instructions. It also allows them to provide status updates and proof of pickup/delivery on these consignments.

    To use this API, subcontractors must be registered and set up as an API user  within our Intermodal TMS. Please discuss registration with your Kuehne+Nagel Intermodal operations point of contact.'
  contact:
    name: Global TOPS API Support
    url: https://home.kuehne-nagel.com/en/service-request-api?lead_topic=intermodal-transport-execution
    email: tops-technical@kuehne-nagel.com
  version: v1
  x-api-id: b576b932-7583-4076-838b-32d6064a8a2d
  x-api-guideline-version: 1.11.7
  x-api-version: 1.0.0
servers:
- url: https://gateway.api.kuehne-nagel.com/transport/execution/pickup-and-delivery/sea/v1
- url: http://gateway.api.kuehne-nagel.com:8280/transport/execution/pickup-and-delivery/sea/v1
security:
- default: []
tags:
- name: GPS Tracking
paths:
  /gps-tracking/{jobId}:
    post:
      tags:
      - GPS Tracking
      summary: Submit GPS tracking data
      description: Submits GPS tracking data for a specific job.
      operationId: subcontractorimportgps
      parameters:
      - name: X-KN-Country-Code
        in: header
        description: Unique country identifier for a specific Kuehne+Nagel Operating Company.
        required: true
        style: simple
        explode: false
        schema:
          $ref: '#/components/schemas/CountryCode'
      - name: X-KN-Request-ID
        in: header
        description: 'UUID identifying the request which will be generated by the client.

          '
        required: true
        style: simple
        explode: false
        schema:
          $ref: '#/components/schemas/RequestId'
      - name: jobId
        in: path
        description: Unique identifier of the assigned consignment job. This value can be found in consignment.job.id from the AssignedConsignment response.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: 1525808-1690222-918
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GPSTrackingRequest'
        required: true
      responses:
        '201':
          description: GPS tracking data uploaded successfully
          headers:
            X-KN-Request-ID:
              description: The same UUID that was originally provided by the client to identify the request.
              style: simple
              explode: false
              schema:
                $ref: '#/components/schemas/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GPSTrackingResponse'
        default:
          description: Error occurred - see status code and problem object for more information.
          headers:
            X-KN-Request-ID:
              description: The same UUID that was originally provided by the client to identify the request.
              style: simple
              explode: false
              schema:
                $ref: '#/components/schemas/RequestId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - default: []
      x-auth-type: Application & Application User
      x-throttling-tier: Unlimited
components:
  schemas:
    Problem:
      required:
      - detail
      - title
      type: object
      properties:
        type:
          type: string
          description: A URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-7807, it is neither recommended to be dereferencable and point to a human-readable documentation nor globally unique for the problem type.
          format: uri-reference
          example: /problem/connection-error
          default: about:blank
        title:
          maxLength: 50
          type: string
          description: A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.\n
          example: Service Unavailable
        status:
          minimum: 100
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.\n
          format: int32
          example: 503
          exclusiveMaximum: 600
        detail:
          maxLength: 500
          type: string
          description: A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.\n
          example: Connection to database timed out
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code.\n
          format: uri-reference
          example: /problem/connection-error#token-info-read-timed-out
    CountryCode:
      maxLength: 5
      type: string
      description: 'Unique country identifier for a specific Kuehne+Nagel Operating Company.

        '
      example: DE
    GPSTrackingRequest:
      required:
      - gpsDateTime
      - latitude
      - longitude
      - senderUniqueShortName
      - uniqueTransportReference
      type: object
      properties:
        senderUniqueShortName:
          maxLength: 8
          type: string
          description: Unique internal identifier of the message sender. This must be same as consignment.recipientUniqueShortName from the AssignedConsignment response.
          example: VRTRAN
        uniqueTransportReference:
          maxLength: 20
          type: string
          description: A unique reference of Kuehne+Nagel's transport order. This is the same as the consignment.job.uniqueTransportReference from the AssignedConsignment response.
          example: 9071410039-01
        gpsDateTime:
          type: string
          description: Timestamp of the GPS data recording, expressed in local time, formatted as YYYY-MM-DDTHH:mm:ss[+/-HH:mm].
          format: date-time
          example: '2025-04-04T08:14:55Z'
        longitude:
          type: number
          description: Longitude coordinate of the transport unit's location.
          format: double
          example: 10.006112132404917
        latitude:
          type: number
          description: Latitude coordinate of the transport unit's location.
          format: double
          example: 53.547707750707815
        locationAddress:
          maxLength: 100
          type: string
          description: Address of the corresponding GPS coordinates, if available.
          example: Narcyzowa 15, 62-023 gmina Kórnik, Poland
        speed:
          minimum: 0
          type: number
          description: Speed at which the transport unit (truck, train, or barge) is moving at the specified location, measured in kilometers per hour, must be non-negative.
          format: float
          example: 60.5
        navigationHeading:
          maximum: 360
          minimum: 0
          type: integer
          description: Direction in which the transport unit is moving at the recorded location. Expressed in degrees from 0 to 360, with 0 representing true North, 90 true east, 180 true south, and 270 true west.
          format: int32
          example: 180
    RequestId:
      maxLength: 36
      type: string
      description: 'UUID identifying the request which will be generated by the client.

        '
      format: uuid
      example: 019a1641-02a3-7a08-a83b-de93c338ed0e
    GPSTrackingResponse:
      type: object
      properties:
        message:
          maxLength: 500
          type: string
          description: GPS tracking response message.
          example: GPS data updated successfully
  securitySchemes:
    default:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://gateway.api.kuehne-nagel.com/authorize
          scopes: {}
x-wso2-api-key-header: ApiKey