{
  "openapi": "3.1.0",
  "info": {
    "title": "Croatian Ferries API",
    "version": "2026-09-06",
    "description": "Read-only, no-auth, no-rate-limit JSON for every Croatian car-ferry route in Croatia: routes, per-route and per-port timetables, and live port-queue snapshots. Regenerated from the operator's published schedules. Machine-readable companion to https://croatianferries.com.",
    "contact": {
      "name": "ZaZet Solutions d.o.o.",
      "email": "gal@zazet-solutions.hr"
    }
  },
  "servers": [
    {
      "url": "https://croatianferries.com"
    }
  ],
  "paths": {
    "/api/routes.json": {
      "get": {
        "operationId": "getAllRoutes",
        "summary": "Every route with its full timetable",
        "description": "The entire dataset in one document.",
        "responses": {
          "200": {
            "description": "The full dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dataset"
                }
              }
            }
          }
        }
      }
    },
    "/api/route/{line}.json": {
      "get": {
        "operationId": "getRouteByLine",
        "summary": "One route by its state-register line number",
        "parameters": [
          {
            "name": "line",
            "in": "path",
            "required": true,
            "description": "Line number, e.g. 401",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A single route",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Route"
                }
              }
            }
          },
          "404": {
            "description": "No route with that line number"
          }
        }
      }
    },
    "/api/port/{portId}.json": {
      "get": {
        "operationId": "getPortDestinations",
        "summary": "Every destination reachable from a port",
        "parameters": [
          {
            "name": "portId",
            "in": "path",
            "required": true,
            "description": "Port id, e.g. zadar",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The port and its destinations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Port"
                }
              }
            }
          },
          "404": {
            "description": "No port with that id"
          }
        }
      }
    },
    "/api/live/merag.json": {
      "get": {
        "operationId": "getLiveQueueMerag",
        "summary": "Live vehicle-queue snapshot for the Merag crossing",
        "responses": {
          "200": {
            "description": "Live queue data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Dataset": {
        "type": "object",
        "required": [
          "operator",
          "routes"
        ],
        "properties": {
          "operator": {
            "type": "string"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "routes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Route"
            }
          }
        }
      },
      "Route": {
        "type": "object",
        "required": [
          "line",
          "name",
          "stops"
        ],
        "properties": {
          "line": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "operator": {
            "type": "string"
          },
          "vessel": {
            "type": "string",
            "description": "Vehicle ferry or catamaran"
          },
          "duration_minutes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "stops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Stop"
            }
          },
          "timetable": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Season"
            }
          }
        }
      },
      "Stop": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "Season": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "valid": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "from": {
                  "type": "string"
                },
                "to": {
                  "type": "string"
                }
              }
            }
          },
          "sailings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Sailing"
            }
          }
        }
      },
      "Sailing": {
        "type": "object",
        "properties": {
          "day_mask": {
            "type": "integer",
            "description": "7-bit weekday mask, Monday = bit 0 ... Sunday = bit 6"
          },
          "stops": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "port": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "departure": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "arrival": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "note_marker": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Port": {
        "type": "object",
        "properties": {
          "port": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "destinations": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
    }
  }
}