API e MCP di Scirocco per sviluppatori e agenti AI
Tutto quello che il sito sa di Scirocco e del meteo del mare, in JSON per programmi e agenti AI. Nessuna registrazione e nessuna chiave: è in sola lettura e ha un limite per IP.
- REST:
https://scirocco.app/v1· OpenAPI 3.1 - MCP (Streamable HTTP, JSON-RPC 2.0 via POST):
https://scirocco.app/mcp - Autenticazione: nessuna
Endpoint
| GET | Cosa restituisce |
|---|---|
| /v1 | Index of the API: endpoints, docs, OpenAPI and MCP links |
| /v1/app | The Scirocco app: platforms, store links, languages, rating, developer, contacts |
| /v1/pricing | Free plan and Scirocco Pro plans with price, billing period and free trial |
| /v1/features | Every feature of the app, grouped by section, with the plan (free or Pro) and what the app does not do |
| /v1/locations | Italian ports, islands and beaches with a marine weather page (filter by area or name, paginated) |
| /v1/locations/{slug} | One location: coordinates, area, weather page links and the nearest locations with distance |
| /v1/locations/{slug}/conditions | Wind, gusts and waves now and tomorrow's summary for one location (cached model data) |
| /v1/areas | Coastal areas (regions and island groups) with their weather page |
| /v1/areas/{slug}/conditions | Wind and waves now and tomorrow for every location of an area (cached model data) |
| /v1/distance | Great-circle distance in nautical miles between two locations, with sailing times at 5, 8, 20 and 30 knots |
| /v1/posts | Blog articles (Italian or English) on boating, navigation, licences, weather and fishing (search, paginated) |
| /v1/posts/{slug} | One blog article with FAQ and, for Italian articles, the full text in markdown |
Server MCP
Endpoint https://scirocco.app/mcp, senza sessione: initialize, tools/list, tools/call, resources/list, resources/read. Manifest: server card e server.json.
get_app_info: What Scirocco is (all-in-one boating app for iPhone), platforms and availability, App Store link, languages, App Store rating, developer and support contact.get_pricing: Free plan limits and Scirocco Pro plans: price in EUR, billing period, free trial days, what Pro adds.list_features: Every feature of the Scirocco app grouped by section (weather, navigation, waypoints, import, tracks, boat, deadlines), each marked free or Pro, plus what the app does not do.search_locations: Find Italian ports, islands and beaches that have a Scirocco marine weather page, by name or area (e.g. 'Procida', 'Sardegna'). Returns slugs to use with the other tools.get_location: Coordinates, area, marine weather page (HTML and markdown) and the nearest locations of one location slug.get_sea_conditions: Wind speed and gusts in knots, direction, wave height now and tomorrow's summary with a go/no-go judgement for a small boat, for one location slug. Data refreshed every few hours; for the full 7-day forecast read the page's markdown.get_area_conditions: Wind and waves now and tomorrow for every location of a coastal area (e.g. 'golfo-di-napoli', 'sardegna').get_distance: Great-circle distance in nautical miles and kilometres between two location slugs, with sailing times at 5, 8, 20 and 30 knots.search_blog_posts: Search Scirocco's blog articles (Italian or English) on boating, navigation, licences, winds, anchoring, maintenance and fishing.get_blog_post: One blog article with its FAQ and, for Italian articles, the full text in markdown.
Esempi
curl https://scirocco.app/v1/pricing
curl "https://scirocco.app/v1/locations?q=procida"
curl https://scirocco.app/v1/locations/procida/conditions
curl "https://scirocco.app/v1/distance?from=napoli&to=capri"
curl -X POST https://scirocco.app/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Dati meteo
Le condizioni (vento, raffiche, direzione, onda adesso e il riepilogo di domani) vengono dai modelli meteo via Open-Meteo (CC BY 4.0) e sono tenute in cache per qualche ora: interrogare più spesso non dà dati più freschi. È un'indicazione, non il bollettino ufficiale. La previsione completa a 7 giorni, le maree e la tendenza a 14 giorni stanno nella pagina di ogni località, anche in markdown (https://scirocco.app/meteo/<slug>.md).
Limiti
60 richieste ogni 60 secondi per IP; 20 ogni 60 secondi sugli endpoint /conditions. Ogni risposta ha gli header RateLimit e RateLimit-Policy; oltre il limite (conteggio approssimato, per data center Cloudflare) arriva un 429 con Retry-After.
Paginazione
Gli elenchi (/v1/locations, /v1/posts) accettano limit (1-200, predefinito 50) e offset, e rispondono con total, count e next: l'URL della pagina successiva, null sull'ultima.
Errori
Gli errori sono application/problem+json (RFC 9457) con type, title, status, detail, un code stabile e resolution, che dice cosa fare.
- not_found
- method_not_allowed
- invalid_parameter
- invalid_lang
- location_not_found
- area_not_found
- post_not_found
- conditions_unavailable
- rate_limited
Versioni e deprecazione (deprecation policy)
La versione è nel percorso (/v1). Aggiunte compatibili (campi o endpoint nuovi) arrivano senza preavviso; una modifica che rompe la compatibilità avrà un nuovo percorso e /v1 resterà attiva almeno 6 mesi dopo l'annuncio, con gli header Deprecation e Sunset. Versione attuale: 1.0.0.