# Ocean Swims NZ

> A community-maintained directory of New Zealand open water swimming events, venue maps, and published swimmer results.

Seasons use the June rollover in Pacific/Auckland: January–May selects the previous calendar year. Public event IDs are season/slug; supported years are 2014–2099, with missing Google Sheet seasons returning 404. Historical 2014–2017 data uses CSV/database sources. Results start in 2018. Registration takes place on external organisers' websites; this site does not accept entries or payments.

## Event data and calendars

- [API catalog](https://oceanswims.nz/.well-known/api-catalog): Standard Linkset discovery of the event API, calendar downloads and documentation.
- [Security contact](https://oceanswims.nz/.well-known/security.txt): Vulnerability reporting contact.

- [Current calendar](https://oceanswims.nz/): Server-rendered event list; individual events carry SportsEvent JSON-LD.
- [API documentation](https://oceanswims.nz/api/docs): Read-only JSON fields, filters, pagination, errors, freshness, and calendar formats.
- [Current JSON events](https://oceanswims.nz/api/events): GET/HEAD; season defaults to current. Use season and event parameters for individual records.
- [Current calendar download](https://oceanswims.nz/calendar.ics): Date-only iCalendar events; optional season/event/location/date filters.
- [Event sitemap](https://oceanswims.nz/sitemap.xml): Current-season canonical URLs.
- [Swimmer sitemap](https://oceanswims.nz/sitemap-swimmers.xml): Current-season published swimmer pages.

## Maps

- [Auckland swim map](https://oceanswims.nz/swimmap-auckland)
- [Wellington swim map](https://oceanswims.nz/swimmap-wellington)

Unknown times, fees, organisers, and addresses must not be inferred. Distances retain source text when they cannot be parsed reliably. Consult official source/registration links for current event details. API cache timestamps describe fetching, not event edits; stale data may be served during upstream outages. Calendar downloads include cancelled events with cancellation status.

## Markdown pages

Pages return 406 when Accept permits neither text/html nor text/markdown. The error lists available types and uses Vary: Accept and Cache-Control: no-store. Specific q=0 exclusions override wildcards.

Request the same calendar, event, swimmer, tally, or swim-map URL with `Accept: text/markdown` to receive UTF-8 Markdown. Normal browsers and wildcard-only requests receive HTML. Responses vary on Accept. Calendar Markdown includes the full loaded season; use the JSON API for filtering. Map Markdown lists landmarks, coordinates and route segments rather than embedding JavaScript. JSON, ICS and XML endpoints keep their native formats.

Explicit Markdown URLs append `.md` to the page path: `/.md`, `/2026/.md` (also `/2026.md`), `/2026/event-slug.md`, `/2026/swimmer/Surname/Firstname.md`, `/2026/tallies.md`, `/swimmap-auckland.md`, and `/swimmap-wellington.md`. These always return Markdown regardless of Accept; the original URLs retain content negotiation and 406 behaviour. Query strings do not affect suffix detection. Missing seasons/events still return 404. Deploy the updated `nginx-routes.conf` include and run nginx -t before reloading. JSON/ICS/XML endpoints have no Markdown aliases.