GulfLine for Developers

Everything the GulfLine app knows is available over a clean, versioned REST API — the app is built on these exact endpoints. Zone timelines and go/no-go plan verdicts, hourly & daily forecasts, marine (tides, buoys, surf), air quality, sun & moon, exposed-rider nowcasts, per-activity suitability, and satellite lightning clearance with configurable pool policies — plus push registration and plan entitlements.

API access is paid & key-gated

While GulfLine is in beta, keys are issued by hand and pricing is worked out per use case — whether that’s a golf-cart platform pulling nowcasts or a pool operator wiring clearance into their front desk. Tell us what you’re building.

Request an API key

Quickstart

Base URL

https://api.gulfline.app

Auth

X-Api-Key header on every request

Honesty contract

Every payload carries meta.source, meta.dataAgeSeconds, and confidence with reasons

curl -H "X-Api-Key: gl_your_key" \
  "https://api.gulfline.app/api/v1/now?lat=29.5075&lon=-95.0949"

Or with the SDK

import { GulfLineClient } from "@gulfweather/sdk";

const gl = new GulfLineClient({ baseUrl: "https://api.gulfline.app", apiKey: process.env.GULFLINE_API_KEY });
const now = await gl.now(29.5075, -95.0949); // typed, retried, RN-ready

Safety note: a lightning clearance status of "unknown" means the feed is stale — treat it as closed. The API will never report a false all-clear. Raw spec: openapi.json

Stability: the API is pinned at /api/v1. Additive changes (new endpoints/optional fields) ship without notice; breaking changes get a new major version with at least 6 months' sunset. Tolerate unknown fields and error codes.

Zones & Location

GET /api/v1/zones

param	type	notes
city	string

responses: 200

GET /api/v1/zones/{zoneId}

param	type	notes
zoneId *	string

responses: 200 · 404

GET /api/v1/locate

param	type	notes
lat *	number
lon *	number

responses: 200

Forecasts & Planning

GET /api/v1/forecast/changes

param	type	notes
lat *	number
lon *	number

responses: 200

GET /api/v1/zones/{zoneId}/timeline

param	type	notes
date	string	Local calendar date in the point's time zone; defaults to today
zoneId *	string

responses: 200 · 404

GET /api/v1/timeline

param	type	notes
lat *	number
lon *	number
date	string	Local calendar date in the point's time zone; defaults to today

responses: 200

GET /api/v1/plan

param	type	notes
lat *	number
lon *	number
start *	string
end *	string

responses: 200 · 400

GET /api/v1/regime

param	type	notes
city	string
lat	number
lon	number
date	string

responses: 200 · 404

GET /api/v1/outlook

param	type	notes
lat *	number
lon *	number

responses: 200

GET /api/v1/hourly

param	type	notes
lat *	number
lon *	number
hours	integer

responses: 200

GET /api/v1/daily

param	type	notes
lat *	number
lon *	number
days	integer

responses: 200

Now, Marine, Air & Sun

GET /api/v1/alerts

param	type	notes
lat *	number
lon *	number

responses: 200

GET /api/v1/nowcast

param	type	notes
lat *	number
lon *	number
minutes	integer

responses: 200

GET /api/v1/sun

param	type	notes
lat *	number
lon *	number

responses: 200

GET /api/v1/radar/forecast

responses: 200

GET /api/v1/marine

param	type	notes
lat *	number
lon *	number

responses: 200

GET /api/v1/air

param	type	notes
lat *	number
lon *	number

responses: 200

GET /api/v1/accuracy

param	type	notes
lat *	number
lon *	number
days	integer
all	string

responses: 200

GET /api/v1/beach

param	type	notes
lat *	number
lon *	number
beach	string	Registry beach id to pin, e.g. stewart-beach; default nearest in reach

responses: 200

GET /api/v1/beaches

param	type	notes
lat *	number
lon *	number

responses: 200

POST /api/v1/beach/feedback

JSON body — e.g. { "query": "pool tomorrow afternoon?", "lat": 29.51, "lon": -95.03 }

responses: 200

GET /api/v1/now

param	type	notes
lat *	number
lon *	number

responses: 200

Tropical & Hurricanes

GET /api/v1/tropical

param	type	notes
lat	number
lon	number

responses: 200

GET /api/v1/tropical/{id}/track

param	type	notes
lat	number
lon	number
id *	string

responses: 200 · 404

Activity Suitability

GET /api/v1/activities

param	type	notes
lat *	number
lon *	number
activity	string

responses: 200

Lightning & Pool Clearance

GET /api/v1/lightning/clearance

param	type	notes
radiusMiles	number
clearMinutes	integer
lat *	number
lon *	number

responses: 200

GET /api/v1/lightning/recent

param	type	notes
lat *	number
lon *	number
radiusMiles	number
minutes	integer

responses: 200

Ask (Natural Language)

POST /api/v1/ask

JSON body — e.g. { "query": "pool tomorrow afternoon?", "lat": 29.51, "lon": -95.03 }

responses: 200 · 403 · 422 · 429 · 503

Push Notifications

POST /api/v1/push/register

JSON body — e.g. { "query": "pool tomorrow afternoon?", "lat": 29.51, "lon": -95.03 }

responses: 200

POST /api/v1/push/unregister

JSON body — e.g. { "query": "pool tomorrow afternoon?", "lat": 29.51, "lon": -95.03 }

responses: 200

Plans & Entitlements

GET /api/v1/plans

responses: 200

GET /api/v1/entitlements

responses: 200

Operational

GET /api/v1/health

responses: 200 · 503

GET /api/v1/dashboards/provider-health.html

responses: 200

GET /api/v1/dashboards/forecast-skill

responses: 200

GET /api/v1/dashboards/forecast-skill.html

responses: 200

GET /api/v1/dashboards/replay-datasets

responses: 200

GET /api/v1/dashboards/replay-datasets.html

responses: 200

GET /api/v1/dashboards/baseline-scores

responses: 200

GET /api/v1/dashboards/baseline-scores.html

responses: 200

GET /api/v1/dashboards/models

responses: 200

GET /api/v1/dashboards/models.html

responses: 200

GET /api/v1/dashboards/usage

responses: 200

GET /api/v1/dashboards/usage.html

responses: 200

GET /api/v1/dashboards/decision-skill

responses: 200

GET /api/v1/dashboards/decision-skill.html

responses: 200

GET /api/v1/openapi.json

responses: 200