Name: Beach Day API: Beach Conditions, Water Quality & Scores
Brand: versusmedia
SKU: api-versusmedia-beach-day-api
Availability: InStock
Author: API Market

Ryan Vinson

# Beach Day API — Beach Discovery, Conditions & Scoring

**Beach Day API** is a coastal data service covering **36,572 beaches across 110 countries**. One key gives you beach search and discovery, full beach records with coordinates and geography, a dated conditions history (weather, ocean, water quality), and a composite **Beach Day Score** you can rank the whole catalogue by.

Every endpoint is a plain synchronous **`GET`** returning JSON, typically in well under a second. Nothing to poll, no job IDs, and one credential — the API.market proxy handles authentication and billing.

---

## What you can build

- **Travel and trip-planning apps** — let users search 36,572 beaches by name, country, or state and show current conditions for each.
- **Beach recommendation tools** — rank by the composite Beach Day Score and surface the best option today.
- **Hotel and vacation-rental guest guides** — enrich a property page with nearby beaches and their conditions.
- **Outdoor recreation dashboards** — combine water temperature, wave height, wind, and water-quality grade into a single go/no-go view.
- **Tourism and destination sites** — build country and state beach directories from `/countries/` and the `country` filter.
- **AI travel assistants** — compact JSON, fast enough to sit inside a chat turn as an agent tool.
- **Location data enrichment** — attach beach names, coordinates, county, and country to your own place records.

---

## Features

- **36,572 beaches, 110 countries** — verified live via `/countries/`, led by the United States (5,276), France (3,991), Italy (3,543), Spain (3,158), and Greece.
- **Full-text search** on beach name.
- **Country and state filters** — by country name (`France`, `Greece`) or state/region code (`FL`, `ES-IB`).
- **Composite Beach Day Score** — a single 0–100 number per beach, with `/beaches/scored/` returning the catalogue ranked best-first.
- **Dated conditions history** — a per-beach series with weather, ocean conditions, water quality, and that day's score.
- **Weather and ocean detail** — air temperature, sky condition, humidity, wind speed, precipitation, water temperature, wave height.
- **Water-quality grades** — letter grade, bacteria level, advisory text, and a **`source`** field so you can check provenance.
- **Geography** — latitude, longitude, city, county, state, country on every record.
- **Offset/limit pagination** — stable, cursor-free paging across the whole dataset.
- **Single-header auth** — one `x-api-market-key`.
- **Sub-second responses** — measured 0.5–1.6s per call through the proxy.

---

## Pricing

| Plan | Price | Included | Limit type | Rate limit |
|:-----|:------|:---------|:-----------|:-----------|
| **Free** | **$0** | **100 calls** | Hard — calls stop at the cap | 1 req/sec |
| **Pro** | **$19 / month** | **10,000 calls** | Hard — calls stop at the cap | 5 req/sec |

Both plans are **hard-limited**: once the quota is used, further calls are rejected rather than billed as overage. No surprise invoice, but track usage and upgrade before you run out.

Pro works out to **$0.0019 per call**. Start on Free — 100 calls is enough to evaluate every endpoint.

> Every request counts as one call, including `/health/`.

---

## API Documentation

### Base URL

```
https://prod.api.market/api/v1/versusmedia/beach-day-api
```

### Authentication

Add your API.market key to every request:

```
x-api-market-key: YOUR_API_KEY
```

Get your key at [api.market](https://api.market/account/apiKeys). This is the only credential you need.

### Endpoints

| Method | Path | Description |
|:-------|:-----|:------------|
| `GET` | `/health/` | Service status check |
| `GET` | `/beaches/` | Search and filter beaches |
| `GET` | `/beaches/{id}/` | Full record for one beach |
| `GET` | `/beaches/{id}/conditions/` | Dated conditions history |
| `GET` | `/beaches/scored/` | Beaches ranked by Beach Day Score |
| `GET` | `/countries/` | Countries with beach counts |

All paths end in a **trailing slash**. Requests without it may not resolve.

---

### GET `/beaches/`

Search and filter the catalogue.

| Parameter | Type | Default | Description |
|:----------|:-----|:--------|:------------|
| `search` | string | — | Match on beach name, e.g. `miami`. |
| `country` | string | — | Full country name, e.g. `France`, `Greece`. |
| `state` | string | — | State or region code, e.g. `FL`, `ES-IB`. |
| `offset` | integer | `0` | Records to skip. |
| `limit` | integer | `100` | Records to return. Values above **500** are capped at 500. |

> The search parameter is **`search`**, not `q`, and paging uses **`offset`**, not `page`. An unrecognised parameter is ignored silently and you get the unfiltered result set, so check that `count` changed when you expect a filter to bite.

```bash
curl "https://prod.api.market/api/v1/versusmedia/beach-day-api/beaches/?search=miami&limit=3" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example response**

```json
{
  "count": 16,
  "results": [
    {
      "id": 16495,
      "name": "Miami Beach",
      "state": "FL",
      "country": "United States",
      "latitude": 25.790654,
      "longitude": -80.130045,
      "nearest_buoy_id": "",
      "nearest_tide_station": "",
      "nudism": "",
      "surf_spot": false,
      "supervised": "",
      "lifeguard": ""
    }
  ]
}
```

`count` is the total number of matches, not the number returned. Page with `offset`.

> `nearest_buoy_id`, `nearest_tide_station`, `supervised`, `lifeguard`, and `nudism` are empty strings on the overwhelming majority of records, and `surf_spot` is almost always `false`. Treat all six as optional and do not build required UI around them.

---

### GET `/beaches/{id}/`

Full record for one beach, including the current conditions block and score.

```bash
curl "https://prod.api.market/api/v1/versusmedia/beach-day-api/beaches/16495/" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Key response fields**

| Field | Type | Description |
|:------|:-----|:------------|
| `id` | integer | Beach ID, used by the other endpoints. |
| `name` | string | Beach name. |
| `country`, `state`, `county`, `city` | string | Geography. May be empty strings. |
| `latitude`, `longitude` | number | Coordinates. |
| `description` | string | Free text. Often empty. |
| `beach_day_score` | integer | Composite 0–100 score. |
| `water_quality` | object \| null | Grade, bacteria level, advisory, and `source`. |
| `weather` | object | `temp_f`, `condition`, `humidity_pct`, `wind_speed_mph`, `precipitation_in`. |
| `ocean_conditions` | object | `water_temp_f`, `wave_height_ft`. |
| `surf_spot` | boolean | Whether the beach is a recognised surf spot. |

Unknown IDs return **`404`**.

---

### GET `/beaches/{id}/conditions/`

Dated conditions history for one beach, most recent first.

| Parameter | Type | Default | Description |
|:----------|:-----|:--------|:------------|
| `offset` | integer | `0` | Records to skip. |
| `limit` | integer | `30` | Records to return. |

```bash
curl "https://prod.api.market/api/v1/versusmedia/beach-day-api/beaches/16495/conditions/?limit=2" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example response**

```json
{
  "beach_id": 16495,
  "count": 7,
  "results": [
    {
      "id": 240561,
      "beach_id": 16495,
      "date": "2026-08-13",
      "water_quality": null,
      "weather": {
        "temp_f": 82,
        "condition": "mostly_clear",
        "humidity_pct": 77,
        "wind_speed_mph": 21.7,
        "precipitation_in": 0
      },
      "ocean_conditions": {
        "water_temp_f": 83,
        "wave_height_ft": 1.9
      },
      "beach_day_score": 61
    }
  ]
}
```

`water_quality` is `null` when no reading exists for that date — check before dereferencing.

When `water_quality` is present it looks like this:

```json
{
  "grade": "B",
  "bacteria_level": "10 cfu/100ml",
  "advisory": null,
  "source": "EEA 2024 classification distribution",
  "updated": "2026-08-12"
}
```

> **Check the `source` field.** Provenance varies by region — European beaches commonly cite `EEA 2024 classification distribution`. If you surface water-quality grades to end users, surface the source with them.

---

### GET `/beaches/scored/`

The catalogue ranked by `beach_day_score`, highest first. Each entry is a full beach record.

| Parameter | Type | Default | Description |
|:----------|:-----|:--------|:------------|
| `offset` | integer | `0` | Records to skip. |
| `limit` | integer | `50` | Records to return. |

```bash
curl "https://prod.api.market/api/v1/versusmedia/beach-day-api/beaches/scored/?limit=3" \
  -H "x-api-market-key: YOUR_API_KEY"
```

Beaches sharing the same score are **not** guaranteed a stable order between calls, so paginated results can repeat or skip entries. If you need deterministic paging, pull a page and sort client-side by `(beach_day_score, id)`.

---

### GET `/countries/`

Every covered country with its beach count, highest first.

```bash
curl "https://prod.api.market/api/v1/versusmedia/beach-day-api/countries/" \
  -H "x-api-market-key: YOUR_API_KEY"
```

```json
{
  "count": 110,
  "results": [
    { "country": "United States", "beach_count": 5276 },
    { "country": "France", "beach_count": 3991 },
    { "country": "Italy", "beach_count": 3543 },
    { "country": "Spain", "beach_count": 3158 }
  ]
}
```

Use the `country` values verbatim as the `country` filter on `/beaches/`.

---

### GET `/health/`

Status check. Still billed as a call.

```json
{ "status": "ok", "service": "Beach Day API" }
```

---

## Status Codes

| Code | Meaning | What to do |
|:-----|:--------|:-----------|
| `200` | Success | Read the response body. |
| `400` | Missing/invalid API key, or an unsupported path or method | Read `message`. Send `x-api-market-key` and use `GET` with the trailing slash. |
| `404` | Unknown beach ID | Verify the `id` came from `/beaches/`. |
| `429` | Rate limited | You exceeded your plan's per-second limit — back off and retry. |
| `5xx` | Upstream error | Retry with backoff; check `/health/`. |

Authentication failures return **`400`**, not `401` or `403`:

```json
{ "message": "No x-api-market-key or x-magicapi-key defined in headers" }
```

```json
{ "message": "Invalid x-api-market-key or x-magicapi-key defined in headers" }
```

A wrong method or path returns `{ "message": "API Path invalid or doesn't exist" }`, also `400`.

---

## Rate Limits

| Plan | Requests per second | Monthly calls |
|:-----|:--------------------|:--------------|
| Free | 1 | 100 (hard) |
| Pro | 5 | 10,000 (hard) |

Both quotas are **hard limits** — calls are refused, not billed, once you hit the cap. On the Free plan, space requests at least a second apart.

---

## Error Handling

- **Branch on `message`, not just the status code.** Auth problems, bad paths, and bad methods all return `400` with different `message` values.
- **Never retry a `400`** — it will fail identically until the request or key is fixed.
- **Retry `429` and `5xx` with exponential backoff**, starting at 1 second.
- **Null-check `water_quality`** on both the detail record and every conditions row.
- **Confirm your filter applied.** An unrecognised query parameter is ignored rather than rejected, so compare `count` against the unfiltered baseline (36,572).
- **Keep the trailing slash.** `/beaches` is not the same route as `/beaches/`.
- **Cache aggressively.** Beach records and `/countries/` change rarely; conditions change at most daily. With hard-limited quotas, caching is what keeps you inside your plan.

---

## Implementation Guide

### Python — search and enrich

```python
import requests

BASE = "https://prod.api.market/api/v1/versusmedia/beach-day-api"
HEADERS = {"x-api-market-key": "YOUR_API_KEY"}

def search_beaches(term, limit=10, offset=0, country=None, state=None):
    params = {"search": term, "limit": limit, "offset": offset}
    if country:
        params["country"] = country
    if state:
        params["state"] = state

    r = requests.get(f"{BASE}/beaches/", params=params, headers=HEADERS, timeout=15)
    if r.status_code == 400:
        raise RuntimeError(r.json().get("message", "bad request"))
    r.raise_for_status()
    return r.json()

def beach_detail(beach_id):
    r = requests.get(f"{BASE}/beaches/{beach_id}/", headers=HEADERS, timeout=15)
    if r.status_code == 404:
        return None
    r.raise_for_status()
    return r.json()

hits = search_beaches("miami", limit=3)
print(f"{hits['count']} matches")

for b in hits["results"]:
    d = beach_detail(b["id"])
    if not d:
        continue
    wq = d.get("water_quality") or {}
    weather = d.get("weather") or {}
    print(
        f"{d['name']} ({d['state']}, {d['country']}) "
        f"score={d.get('beach_day_score')} "
        f"water={wq.get('grade', 'n/a')} "
        f"air={weather.get('temp_f', 'n/a')}F"
    )
```

### Node.js — top beaches in a country

```javascript
const BASE = "https://prod.api.market/api/v1/versusmedia/beach-day-api";
const HEADERS = { "x-api-market-key": process.env.API_MARKET_KEY };

async function get(path, params = {}) {
  const url = new URL(BASE + path);
  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));

  const res = await fetch(url, { headers: HEADERS });
  const body = await res.json();
  if (res.status === 400) throw new Error(body.message);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return body;
}

async function topBeaches(country, n = 10) {
  const { results } = await get("/beaches/", { country, limit: 500 });

  return results
    .filter((b) => b.beach_day_score != null)
    .sort((a, b) => b.beach_day_score - a.beach_day_score || a.id - b.id)
    .slice(0, n)
    .map((b) => ({ id: b.id, name: b.name, score: b.beach_day_score }));
}

const { count, results } = await get("/countries/");
console.log(`${count} countries, top: ${results[0].country} (${results[0].beach_count})`);
console.table(await topBeaches("Greece", 5));
```

### Practical tips

- **Resolve an ID once, then reuse it.** `/beaches/{id}/` already embeds `weather`, `ocean_conditions`, `water_quality`, and the score — on a hard-limited plan, one detail call beats several.
- **Page with `offset`, not `page`.** `page` and `per_page` are not parameters here and are silently ignored.
- **Ask for `limit=500` when sweeping.** That is the server-side ceiling; larger values are clamped, not rejected.
- **Sort ties client-side** by `(beach_day_score, id)` if you page through `/beaches/scored/`.
- **Use `/countries/` to build your country picker** so the values you send as `country` always match exactly.

---

## FAQ

**How many beaches are covered?**

36,572 beaches across 110 countries at the time of writing. Call `/countries/` for the current per-country breakdown.

**What is the Beach Day Score?**

A composite 0–100 rating per beach, also returned per day in the conditions history. `/beaches/scored/` returns the catalogue ranked by it.

**How do I search by name?**

Use `search`, e.g. `/beaches/?search=miami`. The parameter is not `q` — an unknown parameter is silently ignored and you get unfiltered results.

**How does pagination work?**

`offset` and `limit`. `limit` defaults to 100 on `/beaches/`, 50 on `/beaches/scored/`, 30 on `/beaches/{id}/conditions/`, and is capped server-side at 500. There is no `page` parameter.

**Is `count` the number of results returned?**

No. `count` is the total number of matches; `results` holds the current page.

**Why is `water_quality` sometimes null?**

No reading exists for that beach on that date. Always null-check before reading `grade`.

**Where does water-quality data come from?**

It varies by region and is reported per reading in the `source` field. Surface it alongside the grade if you show grades to end users.

**Do I need a Beach Day API account?**

No. `x-api-market-key` is the only credential; the API.market proxy handles authentication upstream.

**Why do auth errors return 400 instead of 401?**

That is how the gateway reports them. Read the `message` field to tell a missing key from an invalid one.

**What happens when I hit my quota?**

Both plans are hard-limited, so calls are refused rather than billed as overage. Upgrade or wait for the next cycle.

**Do the paths really need trailing slashes?**

Yes. Every route ends in `/`, and dropping it may fail to resolve.

---

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Build travel and beach-planning apps with beach discovery, conditions, water quality, weather, and Beach Day scoring for 36,500+ beaches worldwide.