▣ GEOLOCATION · TRAVEL

Compare Beaches Around the World

What it does

Beach Information gives you searchable beach records, local rules, amenities, conditions, and tide forecasts in one API. Use it to look up beaches by country, state, or name, then pull the details you need for a trip planner, beach safety app, or location directory.

List available countries with a beach count, or search beaches with country, state, search, limit, and offset. Search results return each beach's id, name, state, latitude, longitude, nearest_buoy_id, and nearest_tide_station, with optional fields like country, nudism, lifeguard, and surf_spot when available.

For a specific beach id, get the full beach record: description, beach_day_score, water_quality, weather, ocean_conditions, rules, and amenities. Rules are broken out by category and status, and amenities include availability, hours, and notes for items such as restrooms, showers, lifeguards, parking, food, accessibility, and rentals.

Use the conditions and tide endpoints when you need time-based data. Beach conditions return dated entries with water_quality, weather, ocean_conditions, tides, and beach_day_score. Tide forecasts return beach_id and a list of tide_predictions by date, each with its tide entries.

▣ ENDPOINT 01 / 08

GET

List available countries

https://api.eu.apyhub.com/ryanvinson/beaches-information/countries

QUICKSTART

GUIDE

Quickstart

This GET request fetches the beach counts summary from the endpoint.

curl -X GET "https://api.eu.apyhub.com/ryanvinson/beaches-information/countries" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a count integer and a results array. Each item in results is an object with a country string and a beach_count integer.

{
  "count": 2,
  "results": [
    {
      "country": "Greece",
      "beach_count": 12
    },
    {
      "country": "Croatia",
      "beach_count": 8
    }
  ]
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns a list of countries available from the service, along with the total count and per-country beach counts.

Response

Returns a JSON object with a count integer field and a results array field. Each item in results is an object containing a country string and a beach_count integer.

Parameter	Type	Mandatory	Description
count	Integer	Yes	Total number of countries in the response.
results	Object Array	Yes	List of country records. Each item includes `country` and `beach_count`.
results[].country	String	Yes	Country name.
results[].beach_count	Integer	Yes	Number of beaches in this country.

Parameters

No parameters.

▣ ENDPOINT 02 / 08

GET

Search Beaches

https://api.eu.apyhub.com/ryanvinson/beaches-information

QUICKSTART

GUIDE

Quickstart

List beach records with the default limit.

curl -X GET "https://api.eu.apyhub.com/ryanvinson/beaches-information?limit=100&offset=0" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with two required top-level fields: count as an integer, and results as an array of beach objects. Each result includes id, name, state, latitude, longitude, nearest_buoy_id, and nearest_tide_station.

{
  "count": 47,
  "results": [
    {
      "id": 1,
      "name": "Venice Beach",
      "state": "CA",
      "latitude": 33.985,
      "longitude": -118.469,
      "nearest_buoy_id": "46025",
      "nearest_tide_station": "9410660"
    }
  ]
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Searches for beaches and returns a paginated list of matching beach records along with the total count. You can filter the results by state, search text, and country, and control pagination with limit and offset.

Query Parameter(s)

Attribute	Type	Mandatory	Description
limit	Integer	No	Maximum number of results to return. Default: `100`. Maximum: `500`.
state	String	No	Filter by state.
offset	Integer	No	Number of results to skip before returning matches. Default: `0`.
search	String	No	Search term used to match beaches.
country	String	No	Filter by country.

Response

Returns a JSON object with a count integer field and a results array field. count is the total number of matching beaches, and results contains beach objects with the fields defined below.

Parameter	Type	Mandatory	Description
count	Integer	Yes	Total number of matching results. Minimum: `0`.
results	Object Array	Yes	Array of beach objects. Each item includes the fields below.
results[].id	Integer	Yes	Beach identifier. Read-only.
results[].name	String	Yes	Beach name.
results[].state	String	Yes	Two-letter US state code or compound AU code such as `AU-NSW`.
results[].nudism	String	No	Nudism-related attribute.
results[].country	String	No	Country name.
results[].latitude	Number	Yes	Latitude coordinate. Nullable. Format: float.
results[].lifeguard	String	No	Lifeguard-related attribute.
results[].longitude	Number	Yes	Longitude coordinate. Nullable. Format: float.
results[].surf_spot	Boolean	No	Indicates whether the beach is a surf spot. Default: `false`.
results[].supervised	String	No	Supervision-related attribute.
results[].nearest_buoy_id	String	Yes	Identifier of the nearest buoy. Minimum length: `0`.
results[].nearest_tide_station	String	Yes	Identifier of the nearest tide station. Minimum length: `0`.

Query parameters

Name

Type

Description

limitOPTIONAL

integer

—

DEFAULT 100

stateOPTIONAL

string

—

offsetOPTIONAL

integer

—

DEFAULT 0

searchOPTIONAL

string

—

countryOPTIONAL

string

—

▣ ENDPOINT 03 / 08

GET

Get Beach Details

https://api.eu.apyhub.com/ryanvinson/beaches-information/:id

QUICKSTART

GUIDE

Quickstart

Fetch a beach record by its id path parameter.

curl -X GET "https://api.eu.apyhub.com/ryanvinson/beaches-information/:id" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with these top-level fields: id (integer), name (string), state (string), latitude (number or null), longitude (number or null), description (string), nearest_buoy_id (string), nearest_tide_station (string), beach_day_score (number or null), water_quality (object or null), weather (object or null), ocean_conditions (object or null), rules (array of objects), and amenities (array of objects). The id field is read-only.

{
  "id": 123,
  "name": "Example Beach",
  "state": "CA",
  "latitude": 34.0123,
  "longitude": -118.4951,
  "description": "A sample beach record.",
  "nearest_buoy_id": "buoy-001",
  "nearest_tide_station": "tide-station-01",
  "beach_day_score": 8.5,
  "water_quality": {},
  "weather": {},
  "ocean_conditions": {},
  "rules": [],
  "amenities": []
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns the details for a single beach identified by its path id. The response is a JSON object containing the beach’s core profile fields, plus rule, amenity, weather, water quality, and ocean condition data where provided.

Path Parameter(s)

Attribute	Type	Mandatory	Description
id	Integer	Yes	Beach identifier in the path.

Response

Returns a JSON object with these top-level fields: id (integer), city (string), name (string), rules (array of objects), state (string), county (string), nudism (string), country (string), weather (object, nullable), latitude (number, nullable), amenities (array of objects), lifeguard (string), longitude (number, nullable), surf_spot (boolean), supervised (string), description (string), water_quality (object, nullable), beach_day_score (number, nullable), nearest_buoy_id (string), ocean_conditions (object, nullable), and nearest_tide_station (string). The required response fields are the beach’s main identifying and detail fields, and the nested arrays describe rule and amenity records.

Parameter	Type	Mandatory	Description
id	Integer	Yes	Beach identifier. Read-only.
city	String	No	City associated with the beach.
name	String	Yes	Beach name.
rules	Object Array	Yes	Array of rule objects. Each item includes `category` (enum: `dogs`, `alcohol`, `fires`, `smoking`, `camping`, `drones`, `parking`, `other`), `status` (enum: `allowed`, `prohibited`, `restricted`, `seasonal`), and `notes` (string).
state	String	Yes	Two-letter US state code or compound AU code such as `AU-NSW`.
county	String	No	County associated with the beach.
nudism	String	No	Nudism-related description or status.
country	String	No	Country name.
weather	Object	No	Weather object. Nullable and may contain additional properties.
latitude	Number	Yes	Latitude in float format. Nullable in the schema.
amenities	Object Array	Yes	Array of amenity objects. Each item includes `category` (enum: `restrooms`, `showers`, `lifeguard`, `parking_lot`, `food`, `picnic`, `playground`, `accessibility`, `rentals`), `available` (boolean), `hours` (string), and `notes` (string).
lifeguard	String	No	Lifeguard-related information.
longitude	Number	Yes	Longitude in float format. Nullable in the schema.
surf_spot	Boolean	No	Indicates whether the beach is a surf spot. Defaults to `false`.
supervised	String	No	Supervision-related information.
description	String	Yes	Beach description.
water_quality	Object	No	Water quality object. Nullable and may contain additional properties.
beach_day_score	Number	Yes	Beach day score. Nullable in the schema.
nearest_buoy_id	String	Yes	Identifier of the nearest buoy.
ocean_conditions	Object	No	Ocean conditions object. Nullable and may contain additional properties.
nearest_tide_station	String	Yes	Identifier of the nearest tide station.

Path parameters

Name

Type

Description

idREQUIRED

integer

—

▣ ENDPOINT 04 / 08

GET

Get Beach Conditions

https://api.eu.apyhub.com/ryanvinson/beaches-information/:id/conditions

QUICKSTART

GUIDE

Quickstart

Fetch beach-day forecast data for a specific beach ID, with optional paging via query parameters.

curl -X GET "https://api.eu.apyhub.com/ryanvinson/beaches-information/:id/conditions?limit=30&offset=0" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with beach_id as an integer, count as an integer, and results as an array of objects. Each result object includes id, beach_id, date, water_quality, weather, ocean_conditions, tides, and beach_day_score.

{
  "beach_id": 123,
  "count": 1,
  "results": [
    {
      "id": 1,
      "beach_id": 123,
      "date": "2026-07-16",
      "water_quality": {},
      "weather": {},
      "ocean_conditions": {},
      "tides": [],
      "beach_day_score": 8.5
    }
  ]
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns beach condition records for the beach identified by id. The response includes the beach identifier, a total count, and a results array of condition objects.

Path Parameter(s)

Attribute	Type	Mandatory	Description
id	Integer	Yes	Beach identifier.

Query Parameter(s)

Attribute	Type	Mandatory	Description
limit	Integer	No	Maximum number of results to return.<br>Default: 30.<br>Maximum: 200.
offset	Integer	No	Number of results to skip before returning items.<br>Default: 0.

Response

Returns a JSON object with beach_id as an integer, count as an integer, and results as an array of objects. Each object in results contains the beach condition fields defined by the schema.

Parameter	Type	Mandatory	Description
beach_id	Integer	Yes	Beach identifier.
count	Integer	Yes	Total count of returned items.
results	Object Array	Yes	Array of beach condition objects.
results[].id	Integer	Yes	Read-only record identifier.
results[].beach_id	Integer	Yes	Beach identifier.
results[].date	String	Yes	Date in `date` format.
results[].water_quality	Object	Yes	Water quality details. Nullable.
results[].weather	Object	Yes	Weather details. Nullable.
results[].ocean_conditions	Object	Yes	Ocean conditions details. Nullable.
results[].tides	Object Array	Yes	Tide details. Nullable.
results[].beach_day_score	Number	Yes	Beach day score. Nullable.

Path parameters

Name

Type

Description

idREQUIRED

integer

—

Query parameters

Name

Type

Description

limitOPTIONAL

integer

—

DEFAULT 30

offsetOPTIONAL

integer

—

DEFAULT 0

▣ ENDPOINT 05 / 08

GET

Get Top Rated Beaches

https://api.eu.apyhub.com/ryanvinson/beaches-information/scored

QUICKSTART

GUIDE

Quickstart

List beaches with the default page size.

curl -X GET "https://api.eu.apyhub.com/ryanvinson/beaches-information/scored?limit=50&offset=0" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with count and results fields. count is an integer, and results is an array of beach objects; each item includes fields such as id, name, state, latitude, longitude, description, nearest_buoy_id, nearest_tide_station, beach_day_score, water_quality, weather, ocean_conditions, rules, and amenities.

{
  "count": 1,
  "results": [
    {
      "id": 123,
      "name": "Bondi Beach",
      "state": "NSW",
      "latitude": -33.8908,
      "longitude": 151.2743,
      "description": "Popular beach in Sydney.",
      "nearest_buoy_id": "buoy-001",
      "nearest_tide_station": "Bondi",
      "beach_day_score": 8.5,
      "water_quality": {},
      "weather": {},
      "ocean_conditions": {},
      "rules": [],
      "amenities": []
    }
  ]
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns a paginated list of top rated beaches. You can control the page size and starting position with query parameters, and the response includes the total count plus an array of beach records.

Query Parameter(s)

Attribute	Type	Mandatory	Description
limit	Integer	No	Maximum number of results to return. Default: 50. Maximum: 200.
offset	Integer	No	Number of results to skip before returning items. Default: 0.

Response

Returns a JSON object with a count integer field and a results array field. Each item in results is a beach object containing the fields defined below.

Attribute	Type	Mandatory	Description
count	Integer	Yes	Total number of matching beaches.
results	Object Array	Yes	Array of beach objects. Each item includes `id`, `name`, `state`, `latitude`, `longitude`, `description`, `nearest_buoy_id`, `nearest_tide_station`, `beach_day_score`, `water_quality`, `weather`, `rules`, and `amenities` as required fields.

Query parameters

Name

Type

Description

limitOPTIONAL

integer

—

DEFAULT 50

offsetOPTIONAL

integer

—

DEFAULT 0

▣ ENDPOINT 06 / 08

GET

Get Beach Rules

https://api.eu.apyhub.com/ryanvinson/beaches-information/:id/rules

QUICKSTART

GUIDE

Quickstart

Fetch the beach rules for a specific beach ID. Replace 123 with the beach ID you want to look up.

curl -X GET "https://api.eu.apyhub.com/ryanvinson/beaches-information/:id/rules" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a required beach_id integer and a required rules array. Each item in rules is an object with category, status, and notes fields.

{
  "beach_id": 123,
  "rules": [
    {
      "category": "dogs",
      "status": "allowed",
      "notes": "Dogs are allowed on the south side."
    }
  ]
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Retrieves the rules for a specific beach identified by its integer id, returning the beach identifier and a list of rule objects.

Path Parameter(s)

Attribute	Type	Mandatory	Description
id	Integer	Yes	The beach identifier.

Response

Returns a JSON object with required beach_id integer and rules array fields.

Parameter	Type	Mandatory	Description
beach_id	Integer	Yes	The beach identifier.
rules	Object Array	Yes	An array of rule objects. Each item includes `category`, `status`, and `notes`.
rules[].category	ENUM	Yes	Rule category. Allowed values: `dogs`, `alcohol`, `fires`, `smoking`, `camping`, `drones`, `parking`, `other`.
rules[].status	ENUM	Yes	Rule status. Allowed values: `allowed`, `prohibited`, `restricted`, `seasonal`.
rules[].notes	String	Yes	Additional notes for the rule.

Path parameters

Name

Type

Description

idREQUIRED

integer

—

▣ ENDPOINT 07 / 08

GET

Get Beach Amenities

https://api.eu.apyhub.com/ryanvinson/beaches-information/:id/amenities

QUICKSTART

GUIDE

Quickstart

Fetch a beach’s amenities by its path id.

curl -X GET "https://api.eu.apyhub.com/ryanvinson/beaches-information/:id/amenities" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a beach_id integer and an amenities array of objects. Each amenity object includes category (string enum), available (boolean), hours (string), and notes (string).

{
  "beach_id": 123,
  "amenities": [
    {
      "category": "restrooms",
      "available": true,
      "hours": "08:00-20:00",
      "notes": "Near the main entrance"
    }
  ]
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Retrieves the amenities information for a specific beach identified by its numeric id. The response returns the beach’s beach_id and an amenities array.

Path Parameter(s)

Attribute	Type	Mandatory	Description
id	Integer	Yes	Numeric beach identifier in the path.

Response

Returns a JSON object with a beach_id integer field and an amenities array field. Each item in amenities is an object containing category, available, hours, and notes.

Parameter	Type	Mandatory	Description
beach_id	Integer	Yes	Numeric identifier of the beach.
amenities	Object Array	Yes	Array of amenity objects. Each item includes `category`, `available`, `hours`, and `notes`.
amenities[].category	ENUM	Yes	Amenity category. Allowed values: `restrooms`, `showers`, `lifeguard`, `parking_lot`, `food`, `picnic`, `playground`, `accessibility`, `rentals`.
amenities[].available	Boolean	Yes	Whether the amenity is available.
amenities[].hours	String	Yes	Hours information for the amenity.
amenities[].notes	String	Yes	Additional notes about the amenity.

Path parameters

Name

Type

Description

idREQUIRED

integer

—

▣ ENDPOINT 08 / 08

GET

Get tide Forecast

https://api.eu.apyhub.com/ryanvinson/beaches-information/tides/:beach_id

QUICKSTART

GUIDE

Quickstart

Fetch tide predictions for a beach by its beach_id path parameter.

curl -X GET "https://api.eu.apyhub.com/ryanvinson/beaches-information/tides/:beach_id" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a beach_id integer and a tide_predictions array. Each item in tide_predictions is an object with a date string in YYYY-MM-DD format and a tides array of objects.

{
  "beach_id": 123,
  "tide_predictions": [
    {
      "date": "2026-07-16",
      "tides": []
    }
  ]
}

TRY ITLIVE · 10 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns the tide forecast for a specific beach identified by beach_id. The response is a JSON object containing the beach_id and a tide_predictions array.

Path Parameter(s)

Attribute	Type	Mandatory	Description
beach_id	Integer	Yes	Identifies the beach to fetch the tide forecast for.

Response

Returns a JSON object with a beach_id integer field and a tide_predictions array field. Each item in tide_predictions is an object with a date string in date format and a tides array of objects.

Attribute	Type	Mandatory	Description
beach_id	Integer	Yes	The beach identifier included in the response.
tide_predictions	Object Array	Yes	A list of tide forecast objects. Each item contains `date` and `tides`.
tide_predictions[].date	String	Yes	The forecast date in `date` format.
tide_predictions[].tides	Object Array	Yes	A list of tide objects for that date. The inner object shape is not further defined in the schema.

Path parameters

Name

Type

Description

beach_idREQUIRED

integer

—

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.