# Croatian buoy mooring prices: public data API

This read-only endpoint exposes the same maintained buoy catalogue and tariff
functions as the [Croatia buoy and anchorage article](https://abavela.com/en/croatia-buoy-mooring-prices.html).
No API key, login or yacht-inventory request is required. It does not accept
bookings or report live buoy availability.

- [Catalogue JSON](https://abavela.com/api/buoy-prices.php?v=1)
- [Catalogue and original source rules CSV](https://abavela.com/api/buoy-prices.php?v=1&format=csv)
- [12 m × 3.8 m monohull, Split, 15 July](https://abavela.com/api/buoy-prices.php?v=1&type=monohull&loa=12&beam=3.8&region=Split&period=07-15)
- [12 m × 6.5 m catamaran, all researched regions, 15 January](https://abavela.com/api/buoy-prices.php?v=1&type=catamaran&loa=12&beam=6.5&period=01-15)
- [OpenAPI 3.1 specification](https://abavela.com/api/buoy-prices.openapi.json)
- [Maintained source catalogue](https://abavela.com/data/buoy-moorings/catalogue.json)

## Requests

Use GET or HEAD on `/api/buoy-prices.php`; OPTIONS describes allowed methods.
All query parameters are scalar strings. Unknown parameters, arrays, invalid
values and unsupported durations return HTTP 400. Supply metres with a decimal
point, not a localized comma.

| Parameter | Meaning |
| --- | --- |
| `v` | API major version; currently `1` (default). |
| `type` | `monohull` (default) or `catamaran`. |
| `loa`, `beam` | Both are required for boat-specific prices. Positive overall length up to 100 m and beam up to 30 m; beam must be less than length. With neither, return catalogue discovery without a selected-boat price. |
| `period` | `MM-DD`, required when dimensions are supplied. Selects a recurring tariff band, not a dated reservation. The API never silently assumes a summer date. |
| `duration` | `daily` only (default). The maintained buoy engine has no annual, monthly or multi-day contract product. No daily fee is multiplied or divided to invent such products. |
| `region` | `all` (default), `Istria`, `Kvarner`, `Zadar`, `Šibenik`, `Split` or `Dubrovnik`. ASCII `Sibenik` is accepted. |
| `location` | Exact stable location ID from catalogue results. An unknown ID or an ID outside the other filters returns HTTP 404. |
| `search` | Up to 100 characters, matching bay, island and maintained aliases. Short names such as `Vis` match whole words, preventing incidental matches in Bobovišća. |
| `sort` | `price` (default) or `name`. Missing prices follow priced rows and do not become zero-price offers. |
| `format` | `json` (default) or `csv`. CSV has identical rows and raw rule metadata in JSON columns. |

## Interpretation

The JSON envelope contains the normalized `request`, catalogue and result
counts, `comparisonUrl`, source-check dates, limitations and `results`.
`catalogueCheckedOn` identifies the catalogue snapshot. `latestSourceCheck` is
only the newest individual source check in the returned rows; it does not mean
every source was checked then. Source years and validity dates may be older or
unknown and must not be replaced with the current year.

Each result identifies its location, island, region and mooring category.
`price` is present only when the shared buoy engine can calculate a numeric
daily mooring rate for that exact overall length, beam, hull and period.
Its numeric `minimum` and `maximum` retain cents in EUR, with
`includesApplicableVat`, `vatTreatment` and `isStartingPrice` disclosed.
Display examples round to whole euros; do not reparse rounded display text for
calculations. Beam is retained as an explicit boat assumption; the current
tariff engine does not invent a beam surcharge where a buoy source has none.

| `status` | Meaning |
| --- | --- |
| `priced` | Tax-confirmed numerical tariff calculated by the maintained engine. Starting prices and unresolved extras still require the stated caveats. |
| `included` | Mooring conditionally included, for example with a restaurant meal or valid park ticket. `price` remains null; this is never an unconditional zero-euro offer. |
| `quote-required` | A payable total cannot reliably be calculated: absent tariff, unconfirmed VAT or catamaran billing, a band boundary, or an exceeded tariff/physical limit. |
| `unavailable` | No published tariff covers the selected month-day period. Confirm seasonal operation; this is not an occupancy report. |
| `selection-required` | Catalogue discovery without a selected boat; source rules remain available. |

`tariffRules` is a lossless copy of the maintained rule for the location. The
engine handles flat per-boat prices, exact or commenced metre/foot billing,
ordered length bands and gaps, seasonal intervals (including New Year wrap),
explicit multihull factors, mandatory factors and summed components. Source
bands and separate physical `mooringMaxLoaMetres` are different concepts: a
flat source tariff may have no price band even when a buoy's size limit exists.
Missing or uncertain rules are not extrapolated.

`compulsoryCharges.includedComponents` and `mandatoryMultiplier` document the
explicit source charges included by the engine. They do not certify that every
possible invoice charge is known. Always read `priceNote`, `explanation`,
`unpricedExtras`, `restrictions` and original source conditions.

`publishedFlatRate` preserves a published flat source amount even when the
selected boat cannot use the buoy or a payable quote is unavailable. It must
not be presented as that boat's calculated price. `advertisedPrices` retains
operator advertisements and secondary guide references with their dates and
terms. These references never override the calculator or enter numeric price
ranking. `parkAdmission` contains a separately verified entrance ticket quote
where supported; `parkAdmissionRules` preserves the original ticket rules.
A park ticket is not automatically a buoy fee.

`source.type` distinguishes an operator, park, port authority or third-party
directory. A directory entry is evidence of a recorded location, not an
official tariff or confirmation of current deployment, visitor eligibility,
concession status or capacity. Cite original source URLs, tariff years and
check dates with the selected boat and period. Older and undated tariffs need
operator reconfirmation before arrival.

## CSV and caching

CSV is UTF-8 with a header and CRLF records, served as `text/csv`. Empty numeric
fields mean unknown or not calculated, never zero. `*_json` columns preserve
rule objects, advertised references, required components, ticket rules and
unpriced extras without flattening away qualifications. JSON and CSV contain
the same selection and locations; documented numeric prices agree.

Successful responses expose ETag and documentation Link headers and permit
public caching for one hour with revalidation. `If-None-Match` may return 304.
Errors are not cached. Cross-origin read access is allowed; no credentials or
private booking data are exposed. Error JSON uses `ok: false` and an
`error.code` / `error.message`: 400 invalid parameters, 404 missing location,
405 unsupported method, or 503 temporarily unavailable maintained tariffs.

## Article and reference tables

Each language has one canonical buoy article. Share calculator parameters on
that article; the canonical remains the unparameterized localized URL. Native
closed disclosures at `#buoy-price-tables` contain four complete reference
comparisons: a 12 m × 3.8 m monohull and a 12 m × 6.5 m catamaran on 15 July
and 15 January, one daily mooring charge, all researched regions. The source
year is retained per row. Their HTML, sources and conditions exist before
JavaScript; readers can expand them without JavaScript. A fifth source-rules
table retains published bands, advertisements and separate ticket rules.

The maintained `data/buoy-moorings/catalogue.json` is authoritative. Neither
reference HTML nor CSV is an independent editable tariff database. Regenerate
reference blocks with `node scripts/build_buoy_consolidation.cjs`, then run the
article consolidation builder. Do not edit table prices manually. Crawlable
data and structured metadata make interpretation possible; they do not
guarantee search indexing, rankings or citation by any AI service.