KEYSTONE API Standard
    KEYSTONE API Standard
    • Overview
    • Data Schema
      • Diagram
      • Transport Operation
      • Vehicle
      • Driver
      • Organization
    • Paths
      • Transport Operation
        • Create new transport operation data
        • Get all transport operation data
        • Get a specific transport operation data by ID
        • Update data for a specific transport operation by ID
        • Delete specific transport operation data by ID
        • Get schedule data related to a specific transport operation by ID
        • Update schedule data for a specific transport operation by ID
        • Get all phase data related to a specific transport operation by ID
        • Append phase data for a specific transport operation by ID
        • Get specific phase data by transport operation ID and phase ID
        • Update specific phase data by transport operation ID and phase ID
        • Get all international consignment notes related to a specific transport operation by ID
        • Append international consignment notes data for a specific transport operation by ID
        • Get specific international consignment notes data by transport operation ID and reference code
        • Update specific international consignment notes data by transport operation ID and reference code
        • Delete specific international consignment notes data by transport operation ID and reference code
        • Get ongoing transport operation data by country code and license plate number
        • Get details about the schedule of the ongoing transport operation by country code and license plate number
        • Get details about all the phases of the ongoing transport operation by country code and license plate number
        • Get specific phase data related to the ongoing transport operation by country code, license plate number, and phase ID
        • Get all international consignment notes related to the ongoing transport operation by country code and license plate number
        • Get specific international consignment notes data related to the ongoing transport operation by country code, license plate number, and reference code
        • Get all locations related to transport operations
        • Get all locations related to transport operations by location mode
        • Create a new eCMR
        • Get a specific eCMR by ID
        • Update an eCMR by ID
        • Delete an eCMR by ID
      • Vehicle
        • Create new vehicle data
        • Get all vehicle data
        • Get vehicle data by country code and license plate number
        • Update vehicle data by country code and license plate number
        • Delete specific vehicle data by country code and license plate number
        • Get details about the geolocation of vehicle by country code and license plate number
        • Append new vehicle's geolocation data by country code and license plate number
        • Get details about the owner of vehicle by country code and license plate number
        • Get details about the insurances of vehicle by country code and license plate number
        • Get details about the insurance of vehicle by country code, license plate number and insurance id
        • Get details about the revisions of vehicle by country code and license plate number
        • Get details about the revision of vehicle by country code, license plate number and revision id
      • Driver
        • Create new driver data
        • Get all driver data
        • Get driver data by country code and vat number
        • Update driver data by country code and vat number
        • Delete specific driver data
        • Get details about the driver's license by country code and vat number
        • Get details about the driver's traffic violations by country code and vat number
        • Get specific driver's traffic violation data by country code, vat number and traffic violation id
        • Get details about the driver's tachograph cards data by country code and vat number
        • Get specific driver's tachograph card data by country code, vat number and tachograph card id
      • Organization
        • Create new organization data
        • Get all organization data
        • Get organization data by organization ID
        • Update organization data by organization ID
        • Delete specific organization data by organization ID

    Overview

    KEYSTONE API Standard OpenAPI Specification is developed by AETHON Engineering as part of the KEYSTONE project (CORDIS: 101103740), an initiative funded by the European Union’s Horizon Europe programme under the auspices of DG CINEA (European Climate, Infrastructure and Environment Executive Agency). This standard is designed to facilitate seamless data exchange within the logistics sector through a set of RESTful APIs.
    It enables streamlined integration across multiple stakeholders, including logistics companies, enforcement agencies, vehicle operators, drivers, and other entities engaged in transport operations.
    This standard supports interoperability and digitalization across the European transport ecosystem.

    Relationship between the KEYSTONE API Standard and Integrating Systems#

    The relationship between the KEYSTONE API Standard and the integrating systems can be conceptually illustrated as follows:
    API Standard.png
    Conceptually, the KEYSTONE API Standard works as a guidance framework: every Data Producer designs their API according to the shared rules, and every Data Consumer queries APIs that adhere to this guidance. This align-to-the-standard approach replaces tangled point-to-point integrations with a scalable, maintainable architecture. Supplementary tools, like client libraries and modular access scripts, further streamline development, making implementation faster and less error-prone.

    Key Features#

    Transport Operations: Manage and track transport operations, including real-time data for transportation phases, route planning, and logistics coordination. This also includes the integration of the eCMR, provided by Open Logistics Foundation (v0.1) under the Open Logistics Foundation License v1.3.
    Vehicle Information: Access data related to vehicles used in transport operations, including geolocation, registration details, and maintenance status.
    Driver Information: Retrieve driver data, including qualifications, licenses, tachograph cards, and violation records.
    Organization Information: Provides organization information for logistics operators, shippers, and receivers.
    This specification ensures that users can integrate the KEYSTONE API Standard into their systems, enabling smooth, seamless, and secure communication within the logistics ecosystem.

    API Structure#

    The KEYSTONE API Standard is divided into the following main categories of endpoints:
    Transport Operations: Covers all aspects of managing and tracking transport operations, including the management of eCMRs.
    Vehicles: Provides access to detailed vehicle data, including geolocation and status.
    Drivers: Includes information about driver qualifications, licenses, and traffic violations.
    Organizations: Manages organization data for logistics operators, shippers, and receivers.
    Each path supports operations such as:
    Create (POST): Add new data.
    Retrieve (GET): Fetch existing data.
    Update (PUT): Replace the entire resource.
    Partial Update (PATCH): Modify specific fields.
    Delete (DELETE): Remove data.

    Tags#

    The API uses tags to categorize endpoints into logical groups:
    Transport Operation: Endpoints for managing transport operations, including schedules, phases, and documents.
    Vehicle: Endpoints for vehicle management, including geolocation, registration, and maintenance.
    Driver: Endpoints for managing driver-related information, such as license and violations.
    Organization: Endpoints for managing organization data, including logistics operators, shippers, and receivers.

    Paths#

    The API defines the following key paths and operations:

    Transport Operations#

    /transport-operations/: Create new transport operation data or retrieve all transport operation data, optionally filtered by operator ID, driver ID, location mode, starting point country code, and ending point country code.
    /transport-operations/{transportOperationId}/: Retrieve, update, or delete specific transport operation data using transport ID, optionally filtered by operator ID.
    /transport-operations/{transportOperationId}/schedules/: Retrieve or update schedule data related to a specific transport operation using transport ID, optionally filtered by operator ID.
    /transport-operations/{transportOperationId}/phases/: Retrieve or append phase data related to a specific transport operation using transport ID, optionally filtered by operator ID.
    /transport-operations/{transportOperationId}/phases/{phaseId}/: Retrieve, update, or delete specific phase data using transport ID and phase ID.
    /transport-operations/{transportOperationId}/documents/: Retrieve or append the international consignment notes data related to a specific transport operation using transport ID, optionally filtered by operator ID.
    /transport-operations/{transportOperationId}/documents/{referenceCode}/: Retrieve, update, or delete specific the international consignment notes data using transport ID and reference code.
    /transport-operations/{countryCode}/{plateNumber}/: Retrieve transport operation data using country code and license plate number, optionally filtered by phase state.
    /transport-operations/{countryCode}/{plateNumber}/schedules/: Retrieve the schedule of a transport operation using country code and license plate number.
    /transport-operations/{countryCode}/{plateNumber}/phases/: Retrieve phase data of a transport operation using country code and license plate number.
    /transport-operations/{countryCode}/{plateNumber}/phases/{phaseId}/: Retrieve specific phase data of a transport operation using country code, license plate number, and phase ID.
    /transport-operations/{countryCode}/{plateNumber}/documents/: Retrieve the international consignment notes data of a transport operation using country code and license plate number.
    /transport-operations/{countryCode}/{plateNumber}/documents/{referenceCode}/: Retrieve specific the international consignment notes data of a transport operation using country code, license plate number, and reference code.
    /transport-operations/locations/: Retrieve all locations related to transport operations.
    /transport-operations/locations/{mode}/: Retrieve all locations related to transport operations by mode.
    /transport-operations/ecmr/: Create a new eCMR.
    /transport-operations/ecmr/{ecmrId}: Retrieve, update, or delete a specific eCMR by its ID.

    Vehicles#

    /vehicles/: Create new vehicle data or retrieve all vehicle data.
    /vehicles/{countryCode}/{plateNumber}/: Retrieve, update, or delete vehicle data by country code and license plate number.
    /vehicles/{countryCode}/{plateNumber}/geolocations/: Retrieve or append new geolocation data for a specific vehicle by country code and license plate number.
    /vehicles/{countryCode}/{plateNumber}/owners/: Retrieve the owner information of a specific vehicle using country code and license plate number.
    /vehicles/{countryCode}/{plateNumber}/insurances/: Retrieve the insurance information of a specific vehicle using country code and license plate number.
    /vehicles/{countryCode}/{plateNumber}/insurances/{insuranceId}/: Retrieve specific insurance data using the country code, license plate number, and insurance ID.
    /vehicles/{countryCode}/{plateNumber}/revisions/: Retrieve the revision information of a specific vehicle using the country code and license plate number.
    /vehicles/{countryCode}/{plateNumber}/revisions/{revisionId}/: Retrieve specific revision data using the country code, license plate number, and revision ID.

    Drivers#

    /drivers/: Create new driver data or retrieve all driver data.
    /drivers/{countryCode}/{vat}/: Retrieve, update, or delete driver data by country code and vat number.
    /drivers/{countryCode}/{vat}/licenses/: Retrieve the driver's license information using the country code and vat number.
    /drivers/{countryCode}/{vat}/traffic-violations/: Retrieve the driver's traffic violation information using the country code and vat number.
    /drivers/{countryCode}/{vat}/traffic-violations/{trafficViolationId}/: Retrieve specific traffic violation data using the country code, vat number, and traffic violation ID.
    /drivers/{countryCode}/{vat}/tachograph-cards/: Retrieve the driver's tachograph card data by country code and vat number.
    /drivers/{countryCode}/{vat}/tachograph-cards/{tachographCardId}/: Retrieve specific tachograph card data using the country code, vat number, and tachograph card ID.

    Organizations#

    /organizations/: Create new organization data or retrieve all organization data, optionally filtered by type.
    /organizations/{organizationId}/: Retrieve, update, or delete organization data by organization ID.

    Data Schema#

    The API uses reusable data structures to ensure consistency:
    Transport Operation: Contains all details related to a transport operation, including phases and international consignment notes.
    Vehicle: Provides vehicle-specific details, including geolocation, registration, and maintenance information.
    Driver: Contains driver-specific information, including qualifications, licenses, and tachograph cards.
    Organization: Contains organization-specific information, including logistics operators, shippers, and receivers.

    Integration Guidelines#

    To integrate the KEYSTONE API Standard into your system:
    1.
    Understand the Data Flow: Familiarize yourself with the data models (schemas) and interactions between endpoints.
    2.
    Authentication: Implement secure authentication mechanisms to ensure only authorized systems can interact with the API.
    3.
    Error Handling: Use standard HTTP status codes to handle errors gracefully.
    4.
    Data Validation: Validate input data before sending requests to the API.
    5.
    Version Control: Monitor updates to the API specification to ensure compatibility.
    6.
    Data Privacy: Adhere to data privacy regulations when handling sensitive information.
    Follow these steps to smoothly integrate and use the KEYSTONE API Standard in your logistics management system or related applications.

    License#

    The KEYSTONE API Standard OpenAPI Specification is licensed under the CC BY 4.0.

    Contact#

    For inquiries, technical support, or feedback, contact the AETHON Engineering team at info@aethon.gr.
    Image 1Image 2
    Next
    Data Schema
    Built with