API e dati per sviluppatori

Panoramica

L'API di Selettive.com espone in JSON gli stessi dati del sito: gare, classifiche complete, atleti e campi gara delle selettive FIPSAS di pesca in apnea dal 2019. È pubblica, in sola lettura e non richiede autenticazione. La specifica OpenAPI 3.1 è su https://selettive.com/openapi.json e il catalogo API (RFC 9727) su https://selettive.com/.well-known/api-catalog.

Endpoint

• GET /api/v1/info — descrizione del dataset e conteggi
• GET /api/v1/stagioni — elenco stagioni con indice e numero di gare
• GET /api/v1/gare?q=&stagione=&zona=&limit= — cerca gare per località, gara, data o vincitore
• GET /api/v1/gare/{stagione}/{gara} — classifica completa di una gara
• GET /api/v1/atleti?q=&limit= — cerca atleti per nome o società
• GET /api/v1/atleti/{nome} — profilo e storico gare di un atleta (es. GAGGINI Gabriele)
• GET /api/v1/luoghi?q=&limit= — cerca campi gara
• GET /api/v1/luoghi/{nome} — tutte le edizioni disputate in una località

Esempi

curl -s "https://selettive.com/api/v1/gare?q=portovenere"
curl -s "https://selettive.com/api/v1/gare/5/0"
curl -s "https://selettive.com/api/v1/atleti?q=gaggini"
curl -s "https://selettive.com/api/v1/atleti/GAGGINI%20Gabriele"
curl -s -H "Accept: text/markdown" https://selettive.com/

Autenticazione e limiti

Nessuna chiave: tutte le richieste sono anonime. Ogni indirizzo IP può fare fino a 60 richieste al minuto. Ogni risposta riporta gli header RateLimit-Policy e RateLimit (draft IETF); oltre il limite l'API risponde 429 con l'header Retry-After.

Errori

Gli errori usano application/problem+json (RFC 9457) con i campi type, title, status, detail, code e resolution. Codici: not_found (404), invalid_parameter (400), method_not_allowed (405), rate_limited (429).

{"type":"https://selettive.com/docs#errori","title":"Not Found","status":404,"detail":"Atleta non trovato","code":"not_found","resolution":"Cerca il nome con GET /api/v1/atleti?q="}

Server MCP

Server Model Context Protocol (Streamable HTTP, JSON-RPC 2.0) su https://selettive.com/mcp. Tool in sola lettura: search_gare, get_gara, search_atleti, get_atleta, search_luoghi, get_luogo, list_stagioni. Risorse: l'archivio gare e l'elenco atleti in markdown. Server card: https://selettive.com/.well-known/mcp/server-card.json.

curl -s -X POST https://selettive.com/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_atleti","arguments":{"q":"gaggini"}}}'

Markdown

Home, gare, atleti, campi gara e queste pagine rispondono in markdown se la richiesta invia Accept: text/markdown. I file sono anche statici sotto https://selettive.com/content/ (es. https://selettive.com/content/gare.md). Istruzioni per LLM: https://selettive.com/llms.txt.