# Beach Conditions & Tide Data API (`versusmedia/beach-day-api-actor`) Actor

Search beaches worldwide and get real-time conditions, water quality grades, tide predictions, weather data, beach rules, amenities, and a proprietary Beach Day Score. Covers 12,000+ beaches across 27+ countries. Export to JSON, CSV, Excel, or connect to webhooks. Works with AI agents via Apify MCP.

- **URL**: https://apify.com/versusmedia/beach-day-api-actor.md
- **Developed by:** [Ryan Vinson](https://apify.com/versusmedia) (community)
- **Categories:** Developer tools, Travel, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Beach Conditions & Tide Data API

Get structured beach condition data — water quality, tides, weather, beach rules, amenities, advisories, and the proprietary Beach Day Score — for **12,000+ beaches** across 27+ countries.

Powered by [Beach Day API](https://beachdayapi.com).

---

### 🎯 What you can do with this Actor

| Use Case | How |
|---|---|
| Find beach conditions in a state today | Run **Search Beaches** + **Get Top Scored Beaches** |
| Get tide predictions for a specific beach | Run **Get Tide Predictions** with a Beach ID |
| Export beach data for a travel app | Run **Search Beaches** → export to JSON/CSV/Excel |
| Monitor conditions daily | Schedule this Actor to run every morning and send results to a webhook |
| Feed an AI agent with coastal data | This Actor is compatible with Apify's MCP server for AI-agent tool calling |

---

### 🗺️ Coverage

**27+ countries:**
United States, Australia, South Africa, Spain, Italy, France, Croatia, Greece, French Polynesia, New Caledonia, Fiji, New Zealand, Thailand, Cambodia, Vietnam, China, Samoa, Tonga, Cook Islands, American Samoa, Tuvalu, Niue, Wallis and Futuna, India, Brazil, Colombia, Uruguay, Ecuador, Chile, Peru

**12,000+ beaches** with data refreshed regularly from government and authoritative public sources:
- EPA BEACH Act monitoring (US)
- NOAA buoy and weather station networks
- State-level monitoring agencies (Australia, South Africa, Spain)
- Open-Meteo weather and ocean models
- OpenStreetMap location data

---

### 🚀 How to use it

#### 1. Select an Operation

| Operation | Description | Input Needed |
|---|---|---|
| 🔍 Search Beaches | Find beaches by name, state, or country | Search query, state, country |
| 🏖️ Get Beach Detail | Full detail for one beach — conditions, score, rules, amenities | Beach ID |
| 🏆 Get Top Scored Beaches | Beaches ranked by current Beach Day Score | State, country (optional) |
| 🌊 Get Tide Predictions | 7-day tide predictions for a beach | Beach ID |
| 📋 Get Beach Rules | Local beach rules (dogs, alcohol, fires, etc.) | Beach ID |
| 🚻 Get Beach Amenities | On-site amenities (restrooms, lifeguards, parking, etc.) | Beach ID |
| 📊 Get Beach Conditions | Historical condition snapshots for a beach | Beach ID |

#### 2. Configure Filters

- **Beach ID** — numeric ID from Search Beaches results
- **State** — filter by state code (e.g. `CA`, `FL`, `AU-NSW`)
- **Country** — filter by country name (e.g. `United States`, `Australia`)
- **Max Results** — max items to return (up to 500)
- **Days** — history window for tides/conditions (up to 7)

#### 3. Run and Export

Once the Actor finishes, you can:
- View results as a table in the Apify Console
- Export as JSON, CSV, Excel, XML, or RSS
- Schedule recurring runs (daily, weekly)
- Connect via webhook to push results into your own system

---

### 📊 Sample Output

Each result row includes:

| Field | Type | Example |
|---|---|---|
| `operation` | string | `get_beach_detail` |
| `id` | integer | 372 |
| `name` | string | "Santa Monica Beach" |
| `city` | string | "Santa Monica" |
| `state` | string | "CA" |
| `country` | string | "United States" |
| `latitude` | float | 34.010 |
| `longitude` | float | -118.496 |
| `beach_day_score` | integer | 73 |
| `water_quality_grade` | string | "Good" |
| `weather_summary` | string | "Sunny, 72°F" |
| `advisory_status` | string | "No advisory" |
| `_raw` | object | Full API response data |

---

### 🤖 AI Agent Usage

This Actor is compatible with Apify's MCP server, making it callable by AI agents and applications. An agent can:

- **Search for beaches** near a location
- **Check current conditions** at a specific beach before recommending it
- **Get tide predictions** for surf-timing questions
- **Compare Beach Day Scores** across multiple nearby beaches

This makes the Actor a natural tool for travel assistants, coastal safety bots, and outdoor activity planners.

---

### 💰 Pricing

This Actor uses **pay-per-event** pricing based on the operation type:

| Tier | Operations | Price per result |
|---|---|---|
| Light | Search Beaches, Tide Predictions, Beach Rules, Beach Amenities | $0.005 |
| Heavy | Beach Detail, Top Scored Beaches, Beach Conditions | $0.01 |

Results are counted per row pushed to the dataset. A search returning 25 beaches = 25 result charges. A single beach detail = 1 result charge.

---

### 📝 Notes

- **Data is as-is from authoritative public sources.** Always verify critical conditions through official channels.
- **Beach Day Scores** range from 0 to 100. Higher scores = better beach-going conditions.
- **Tide data** availability depends on the beach's nearest NOAA/regional tide station.
- **Water quality monitoring schedules** vary by state and country — some beaches refresh daily, others weekly.

---

### 🔗 Links

- [Beach Day API Website](https://beachdayapi.com)
- [API Documentation](https://beachdayapi.com/docs/)
- [Coverage Map](https://beachdayapi.com/coverage/)
- [Terms of Service](https://beachdayapi.com/terms/)
- [Contact Support](https://beachdayapi.com/contact/)

# Actor input Schema

## `operation` (type: `string`):

Which Beach Day API operation to run.
## `query` (type: `string`):

Beach name, city, or keyword to search (only used with Search Beaches operation).
## `beachId` (type: `integer`):

Beach Day API beach ID — required for Beach Detail, Tide Predictions, Rules, Amenities, and Conditions operations.
## `country` (type: `string`):

Filter by country name (e.g. 'United States', 'Australia'). Works with Search Beaches and Top Scored.
## `state` (type: `string`):

Filter by state code (e.g. 'CA', 'FL', 'AU-NSW', 'HI'). Works with Search Beaches and Top Scored.
## `limit` (type: `integer`):

Maximum number of results to return.
## `days` (type: `integer`):

Number of days of condition history or tide predictions (max 7). Only used with tide/conditions operations.

## Actor input object example

```json
{
  "operation": "search_beaches",
  "limit": 25,
  "days": 7
}
````

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("versusmedia/beach-day-api-actor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("versusmedia/beach-day-api-actor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call versusmedia/beach-day-api-actor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=versusmedia/beach-day-api-actor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Beach Conditions & Tide Data API",
        "description": "Search beaches worldwide and get real-time conditions, water quality grades, tide predictions, weather data, beach rules, amenities, and a proprietary Beach Day Score. Covers 12,000+ beaches across 27+ countries. Export to JSON, CSV, Excel, or connect to webhooks. Works with AI agents via Apify MCP.",
        "version": "0.0",
        "x-build-id": "8gBkjYvcsXQ4s4XRn"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/versusmedia~beach-day-api-actor/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-versusmedia-beach-day-api-actor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/versusmedia~beach-day-api-actor/runs": {
            "post": {
                "operationId": "runs-sync-versusmedia-beach-day-api-actor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/versusmedia~beach-day-api-actor/run-sync": {
            "post": {
                "operationId": "run-sync-versusmedia-beach-day-api-actor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "operation"
                ],
                "properties": {
                    "operation": {
                        "title": "Operation",
                        "enum": [
                            "search_beaches",
                            "get_beach_detail",
                            "get_top_scored_beaches",
                            "get_tide_predictions",
                            "get_beach_rules",
                            "get_beach_amenities",
                            "get_beach_conditions"
                        ],
                        "type": "string",
                        "description": "Which Beach Day API operation to run.",
                        "default": "search_beaches"
                    },
                    "query": {
                        "title": "Search Query",
                        "type": "string",
                        "description": "Beach name, city, or keyword to search (only used with Search Beaches operation)."
                    },
                    "beachId": {
                        "title": "Beach ID",
                        "type": "integer",
                        "description": "Beach Day API beach ID — required for Beach Detail, Tide Predictions, Rules, Amenities, and Conditions operations."
                    },
                    "country": {
                        "title": "Country",
                        "type": "string",
                        "description": "Filter by country name (e.g. 'United States', 'Australia'). Works with Search Beaches and Top Scored."
                    },
                    "state": {
                        "title": "State / Region",
                        "type": "string",
                        "description": "Filter by state code (e.g. 'CA', 'FL', 'AU-NSW', 'HI'). Works with Search Beaches and Top Scored."
                    },
                    "limit": {
                        "title": "Max Results",
                        "minimum": 1,
                        "maximum": 500,
                        "type": "integer",
                        "description": "Maximum number of results to return.",
                        "default": 25
                    },
                    "days": {
                        "title": "Days of History",
                        "minimum": 1,
                        "maximum": 7,
                        "type": "integer",
                        "description": "Number of days of condition history or tide predictions (max 7). Only used with tide/conditions operations.",
                        "default": 7
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```