Description

You need an API key to access the Shoreline Design API. Contact your account admin if you need to generate API tokens. Once you've have access, follow the Generate an API token instructions.

The Shoreline Design API provides a fast, automated way to edit case data and submit that data to the Shoreline Design system to run simulations. Use the Design API to quickly run simulations with small changes to analyze the effects. 

Retrieve a partial case JSON through the Design API, make copies of the JSON, edit the copies, and submit the copies through our API. After your simulation runs complete, you can retrieve the results through the API.

See the intended flow in the diagram below. 

Output data from the API—including files stored in S3, simulation registrations in the backend, and post-processed files in the dispatcher—is deleted after 30 days. The 30-day period begins from the moment you submit a simulation request through the POST /simulations endpoint.

Editing a case JSON

You must submit a valid partial case JSON for a simulation run to complete successfully. A partial case JSON contains only key case information for submission through the API.

While you can retrieve run status (in progress, completed, or failed) through an API call, the reason for failure is not given in the API response. 

When editing a partial case JSON for submission through the API, only edit data in the following sections:

  • vesselList 
  • personnelList
  • Under windFarms > infrastructureList > `fixable`
All parameters in your case JSON must match the case type, either a Construction or O&M case. For example, do not change the fixableType of a WTG from INSTALLATION_TASK (a Design parameter) to CORRECTIVE_MAINTENANCE (an O&M parameter).

Generate an API token

Contact your account administrator if you require access to the API Clients section of your account's team settings.

  1. Go to your Team settings.
  2. Click on API Clients.
  3. At the bottom of the table, click New client.
  4. Enter a Name and click the Check (save) icon.
  5. Copy the Identifier and Secret.
  6. Copy the following code and replace {client_id} and {client_secret}with the values from step 5.
    curl -v https://design.shoreline.no/api/oauth2/token -d "client_id={client_id}&client_secret={client_secret}&grant_type=client_credentials" -H "Content-Type: application/x-www-form-urlencoded"
  7. Copy and past the code into your terminal and run it.

The response provides an access_token key and value. Extract the value for this key. This is your API token that you can use to authenticate your API requests.

Base URL

https://design.shoreline.no/api/

Headers

Authorization header

Shoreline authenticates calls with OAuth2 HTTP bearer tokens. 

When you make an API call, use an Authorization HTTP header to provide your API key, with a Bearer prefix. For example: 

Authorization: Bearer {YOUR_API_KEY}

Follow the instructions in the Generate an API token section to create and API token.

Endpoints 

POST /simulations 

POST a case JSON to run a simulation. 

Request body 

{ 
    "runs:": 20, 
    "caseId": 0, 
    "startDate": "2024-01-18", 
    "durationInYears": 30, 
    "case": { 
    "personnelList": {}, 
    "vesselList": {}, 
    "windFarms": {} 
    }   
}

Response

Returns a JSON object with the following properties: 

  • requestId: A unique ID for your simulation request.

Example

Request

curl -X 'POST' \ 

'https://design.shoreline.no/api/simulations' \ 

-H 'accept:application/json' \ 

-H 'Content-Type: application/json' \ 

-H 'Authorization: Bearer {API-KEY}' \

-d '{ 

   "runs:":20, 

   "caseId":1234, 

   "startDate":"2024-01-18", 

   "durationInYears":30, 

   "case": { 

      "personnelList": {...}, 

      "vesselList": {...}, 

      "windFarms": {...} 

   } 

}'

Response

{ 
  "requestId": "1a2bc345-de67-89f0-g1h2-ij3456kl7m89" 
}

Errors

If the request is not successful, the API returns JSON containing the relevant error code. Shoreline uses the following error codes: 

  • 400 Bad Request: The request was malformed or missing required parameters. 
  • 401 Unauthorized: The API key provided was invalid or missing. 
  • 404 Not Found: The requested resource was not found. 
  • 500 Internal Server Error: An unexpected error occurred on the server. 

GET /simulations/{requestId}

Retrieve information on a simulation run request.

Parameters

  • `requestId`: The unique ID for the simulation request. 

Response 

Returns a JSON object with the following properties: 

  • `requestId`: A unique ID for your simulation request. 
  • `runsRequested`: The total number of simulation runs requested. 
  • `runs`: JSON containing information on the requested runs. 

Example 

Request 

curl -X 'GET' \ 

  'https://design.shoreline.no/api/simulations/1a2bc345-de67-89f0-g1h2-ij3456kl7m89"' \ 

  -H 'accept: application/json' \

  -H 'Authorization: Bearer {API-KEY}'

Response

{ 

  "requestId": "1a2bc345-de67-89f0-g1h2-ij3456kl7m89", 

  "runsRequested": 1, 

  "runs": [ 

    { 

      "runNumber": 1, 

      "status": "COMPLETED", 

      "phase": "FINISHED_RUN", 

      "progress": 100, 

      "startedAt": "2023-11-24T11:58:23.219", 

      "availableOutputs": [ 

        "stats", 

        "technician_utilization", 

        "vessel_task_completion", 

        "task_completion", 

        "personnel_hours_summary", 

        "vessel_summary", 

        "vessel_task_summary", 

        "statistics_technical_utilization_monthly", 

        "statistics_technical_utilization_yearly", 

        "statistics_tba", 

        "statistics_tba_root_cause", 

        "statistics_pba", 

        "statistics_pba_root_cause", 

        "statistics_total_operation_days_monthly", 

        "statistics_total_operation_days_yearly", 

        "statistics_total_flying_hours_monthly", 

        "statistics_total_flying_hours_yearly", 

        "statistics_possible_operation_days_monthly", 

        "statistics_possible_operation_days_yearly", 

        "statistics_scheduled_maintenance_completion", 

        "statistics_scheduled_maintenance_completion_monthly_individual", 

        "statistics_component_lost_power_production_yearly", 

        "statistics_component_downtime_yearly", 

        "statistics_man_hours_yearly", 

        "statistics_man_hours_monthly", 

        "statistics_general_costs_yearly", 

        "statistics_general_costs_monthly", 

        "statistics_maintenance_costs_yearly", 

        "statistics_maintenance_costs_monthly", 

        "statistics_vessel_task_costs_yearly", 

        "statistics_vessel_task_costs_monthly", 

        "statistics_tba_monthly_individual", 

        "statistics_tba_monthly_cumulative", 

        "statistics_pba_monthly_individual", 

        "statistics_pba_monthly_cumulative", 

        "statistics_weather_cumulative", 

        "statistics_raw_cost_values_monthly_individual", 

        "statistics_time_spent_per_vessel_monthly_individual", 

        "simulation_info", 

        "process_cycles_log", 

        "process_cycles_log_csv", 

        "log", 

        "logistics_log", 

        "milestones_log", 

        "milestones_log_csv", 

        "inventory_management_log" 

      ] 

    }

Errors

If the request is not successful, the API returns JSON containing the relevant error code. Shoreline uses the following error codes: 

  • 400 Bad Request: The request was malformed or missing required parameters. 
  • 401 Unauthorized: The API key provided was invalid or missing. 
  • 404 Not Found: The requested resource was not found. 
  • 500 Internal Server Error: An unexpected error occurred on the server. 

GET /simulations/{requestId}/runs/{runNumber}/outputs/{output} 

Retrieve a specified output file for a simulation run. 

Parameters

  • requestId: The unique ID for the simulation request. 
  • runNumber: The sequential run ID. 
  • output: The output you want returned. Possible values: 
    • stats 
    • technician_utilization 
    • vessel_task_completion
    • task_completion
    • personnel_hours_summary
    • vessel_summary
    • vessel_task_summary
    • statistics_technical_utilization_monthly
    • statistics_technical_utilization_yearly
    • statistics_tba
    • statistics_tba_root_cause
    • statistics_pba
    • statistics_pba_root_cause
    • statistics_total_operation_days_monthly
    • statistics_total_operation_days_yearly
    • statistics_total_flying_hours_monthly
    • statistics_total_flying_hours_yearly
    • statistics_possible_operation_days_monthly
    • statistics_possible_operation_days_yearly
    • statistics_scheduled_maintenance_completion
    • statistics_scheduled_maintenance_completion_monthly_individual
    • statistics_component_lost_power_production_yearly
    • statistics_component_downtime_yearly
    • statistics_man_hours_yearly;
    • statistics_man_hours_monthly
    • statistics_general_costs_yearly
    • statistics_general_costs_monthly
    • statistics_maintenance_costs_yearly
    • statistics_maintenance_costs_monthly
    • statistics_vessel_task_costs_yearly
    • statistics_vessel_task_costs_monthly
    • statistics_tba_monthly_individual
    • statistics_tba_monthly_cumulative
    • statistics_pba_monthly_individual
    • statistics_pba_monthly_cumulative
    • statistics_weather_cumulative
    • statistics_raw_cost_values_monthly_individual
    • statistics_time_spent_per_vessel_monthly_individual
    • simulation_info
    • process_cycles_log
    • process_cycles_log_csv
    • log
    • logistics_log
    • milestones_log
    • milestones_log_csv
    • testing_work_log
    • inventory_management_log

Response

Returns a JSON object with the following properties: 

  • requestId: A unique ID for your simulation request. 
  • runsRequested: The total number of simulation runs requested. 
  • requestedAt: Timestamp for when the simulation run request was made in ISO 8601 format. 
  • runs: JSON containing information on the requested runs. 

Example

Request 

curl -X 'GET' \ 

  'https://design.shoreline.no/api/simulations/1a2bc345-de67-89f0-g1h2-ij3456kl7m89/runs/1/outputs/technician_utilization' \ 

  -H 'accept: application/octet-stream' \

  -H 'Authorization: Bearer {API-KEY}'

Response

[ { 

  "portId" : "Port of Esbjerg (215393)", 

  "part" : "Tower",de 

  "change" : 0, 

  "currentLevel" : 20, 

  "simDuration" : 0.0, 

  "simDateTime" : "2024-01-19T00:00" 

}, 

... ]

Errors

If the request is not successful, the API returns JSON containing the relevant error code. Shoreline uses the following error codes: 

  • 400 Bad Request: The request was malformed or missing required parameters. 
  • 401 Unauthorized: The API key provided was invalid or missing. 
  • 404 Not Found: The requested resource was not found. 
  • 500 Internal Server Error: An unexpected error occurred on the server.

GET /simulations/copy/{caseId}

Retrieve the case JSON for a specified case.

Parameters

  • caseId: The unique ID for the case. This is the second numerical string in the URL when accessing your case in the Shoreline Design web app. 
  • startDate: The date on which you want your simulation to begin. 
  • durationInYears: The simulation length from the start date. 

Response

Returns a JSON object with the case data.

Example

Request

curl -X 'GET' \ 

  'https://design.shoreline.no/api/simulations/copy/1234?startDate=2024-01-01&durationInYears=5' \ 

  -H 'accept: application/json' \ 

  -H 'Authorization: Bearer {API-KEY}'

Response

{ 
    "windFarms": [...]. 
    "vesselList": [...], 
    "personnelList": [...] 
}

Errors

If the request is not successful, the API returns JSON containing the relevant error code. Shoreline uses the following error codes: 

  • 400 Bad Request: The request was malformed or missing required parameters. 
  • 401 Unauthorized: The API key provided was invalid or missing. 
  • 404 Not Found: The requested resource was not found. 
  • 500 Internal Server Error: An unexpected error occurred on the server.