# Slogarie Estate availability API

Which of the four holiday houses at Slogarie Estate (Galloway, Scotland) are
free, what a stay costs, and where to book it. Read-only, no key, no account.

**Minimum stay: 3 nights, at every house.** A stay of 1 or 2 nights cannot be
booked; nor can one longer than 28 nights. Ask `/api/stay` for fewer than 3
nights and it says so, and offers the nearest 3-night stays as ready URLs.

Start here, no parameters needed:
[https://www.slogarie-estate.co.uk/api/availability](https://www.slogarie-estate.co.uk/api/availability)
is every house, night by night, for the next 30 days. Each date a stay can
start on has a `check` URL that prices that stay and gives its booking link,
and `links.next` is the following 30 days, so every answer can be reached by
following URLs. [https://www.slogarie-estate.co.uk/api](https://www.slogarie-estate.co.uk/api)
lists the starting points.

- Base URL: `https://www.slogarie-estate.co.uk`
- OpenAPI 3.1: [/api/openapi.json](https://www.slogarie-estate.co.uk/api/openapi.json)
- Catalogue (RFC 9727): [/.well-known/api-catalog](https://www.slogarie-estate.co.uk/.well-known/api-catalog)
- Access: [/auth.md](https://www.slogarie-estate.co.uk/auth.md) (anonymous; nothing to register)

The data is live from the estate's booking system, Anytime Booking, and cached
for up to a minute. It is the same data, read the same way, that the calendars
on the site use: what this API says can be booked is what a guest can pick
there. Dates are `YYYY-MM-DD` in Europe/London. Prices are in
pounds sterling and are the total for the stay.

## The houses

| id | House | Sleeps |
| --- | --- | --- |
| `the-coach-house` | The Coach House | 10 |
| `the-lodge` | The Lodge | 10 |
| `keepers-cottage` | Keeper's Cottage | 6 |
| `the-kennels` | The Kennels | 2 |

Every stay is 3 to 28 nights. For anything else, contact the owners at
https://www.slogarie-estate.co.uk/contact.

`GET /api/houses` returns the same list with each house's page.

## Is a stay free, and what does it cost?

```
GET /api/stay?arrival=2027-06-04&nights=7&guests=6
```

| Parameter | Required | Meaning |
| --- | --- | --- |
| `arrival` | yes | Arrival date |
| `nights` | yes | Length of stay, 3 to 28 |
| `house` | no | One house id, or `all` (default) |
| `guests` | no | Leave out houses that sleep fewer |

Each house in `results` has `available`. When it is `true` there is a `price`
and a `bookingUrl`; when `false`, a `reason`.

```json
{
  "house": "keepers-cottage",
  "arrival": "2027-06-04",
  "departure": "2027-06-11",
  "nights": 7,
  "available": true,
  "price": { "amount": 1449, "currency": "GBP" },
  "bookingUrl": "https://slogarieestate.sb.anytimebooking.eu/search/results3/2027-06-04/7/6/0/0/0/3/50779/"
}
```

The `bookingUrl` opens Anytime Booking's search for those dates, where the
guest picks the house and books. The API cannot book on anyone's behalf.

## Which nights are free?

```
GET /api/availability?from=2027-06-01&to=2027-06-30&house=the-lodge
```

`from` defaults to today and `to` to 30 days later; at most 93 days per call.
`house` and `guests` work as above. Each house has a `nights` list, one entry
per night:

Each house starts with `bookableStays`: the stays it can actually book in the
range, each an arrival date, the lengths allowed from it (never under 3
nights), the price of the shortest, and a `check` URL. Quote these to a guest,
not single nights. After it comes `nights`, one entry per night:

- `status`: `available`, `booked`, `unreleased` (not open for booking yet) or
  `past`. `available` means free, not bookable on its own.
- `canArrive`: on an available night, whether a stay can start on it.
- `arrival.stays`: on a night a stay can start, every length that can be
  booked from it and its total price, e.g. `{ "3": 1140, "4": 1520 }`.
- `arrival`: on an available night a stay can start on, the shortest and
  longest stay from that date and the price of the shortest.

A night can be available but not a possible arrival, for example two free
nights between bookings. Check a specific stay with `/api/stay`.

## Errors

Errors are `application/problem+json` with `status`, `title` and `detail`.
`400` is a bad parameter; `502` means the booking system did not answer.
`GET /api/health` reports whether the feed is reachable.
