Garatzaileentzako APIa

• Oinarrizko helbidea: https://trenes.valfiguer.com/api/v1
• Irakurtzeko soilik (GET), erantzunak JSON edo GeoJSON formatuan, UTF-8an eta konprimatuta gzip eskatzen baduzu.
• CORS irekia: nabigatzailetik dei diezaiokezu, edozein domeinutatik. Ez du cookierik ez gakorik erabiltzen.
• Orduak Unix marka gisa segundotan (*_ts) eta ISO 8601 gisa UTCn (*_at).
• OpenAPI zehaztapena: /api/openapi.json · Kontsola interaktiboa: /api/docs

curl -s --compressed https://trenes.valfiguer.com/api/v1/trains | jq '.features | length'

Datuak Renfe Data, FGC Dades Obertes eta Open Data Euskadi (MovEuskadi) iturrietatik datoz, guztiak CC BY 4.0 lizentziapean. Nahi duzunerako erabil ditzakezu, baita helburu komertzialekin ere, iturria aipatzen baduzu. Lerro bat nahikoa da:

Datuak: Renfe Data, FGC eta MovEuskadi (CC BY 4.0), trenes.valfiguer.com bidez

Ez da segurtasun-sistema bat. Kokapenak segundo edo minutu batzuetako atzerapenarekin iristen dira, eta trenak falta daitezke. Ez erabili segurtasun-erabakietarako, eta ez aurkeztu informazio ofizial gisa; ofiziala operadore bakoitzarena eta Adif-ena da.

• IP bakoitzeko 30 eskaera segundoko gehienez, 100eko boladekin. Hortik gora 429 erantzuten du: itxaron segundo bat eta saiatu berriro.
• Kokapenak 15–20 s-tik behin berritzen dira jatorrian. /trains 5 s-tik behin baino maizago eskatzeak ez du ezer berririk ekartzen.
• Erantzun handiek ETag dute: bidali If-None-Match eta 304 jasoko duzu, gorputzik gabe, ezer aldatu ez bada.
• Trafiko handia mugituko baduzu edo historiko osoa behar baduzu, idatzi iezaguzu info@valfiguer.com helbidera.

• delay_s: atzerapena segundotan, operadorearen arabera; null argitaratzen ez badu (FGCk trena garaiz doan ala ez soilik esaten du: begiratu flags).
• reported_at / age_s: noiz hartu zen kokapena eta zer adin zuen erantzuna sortzean. stale: true 3 minutu baino gehiago badaramatza eguneratu gabe.
• flags: datuari aplikatutako zuzenketak edo oharrak, adibidez zuzendutako ordu bat edo ezinezkoa delako baztertutako kokapen bat.
• category: ld (abiadura handia eta distantzia luzea), md (distantzia ertaina), cercanias edo otros (FGC eta Metro Bilbao).

GET/api/v1/trains

Une honetan kokapena argitaratuta duten tren guztiak, GeoJSON FeatureCollection gisa, iturri bakoitzaren egoera feeds eremuan dutela.

Cachea: 5 s, ETag · Probatu

{
  "type": "FeatureCollection",
  "generated_at": "2026-11-01T08:12:30Z",
  "generated_ts": 1793520750,
  "attribution": "Fuentes: Renfe Data (data.renfe.com), FGC Dades Obertes … CC BY 4.0. …",
  "feeds": [{ "id": "renfe_ld_positions", "ok": true, "stale": false, "data_age_s": 14 }],
  "features": [{
    "type": "Feature",
    "id": "renfe_ld:<id>",
    "geometry": { "type": "Point", "coordinates": [-3.6893, 40.4066] },
    "properties": {
      "source": "renfe_ld", "operator": "Renfe", "category": "ld",
      "product": "AVE", "train_number": "00297", "nucleo": null,
      "line_color": null, "origin": "Madrid-Puerta de Atocha", "destination": "Barcelona-Sants",
      "status_text": "en", "stop_name": "Zaragoza-Delicias", "platform": "4",
      "delay_s": 180, "reported_at": "2026-11-01T08:12:16Z", "age_s": 14,
      "stale": false, "speed_kmh": 287, "bearing": 64, "flags": []
    }
  }]
}

GET/api/v1/trains/{id}

Tren bat bere azken ibilbidearekin (80 kokapen arte track eremuan: lon, lat, ordua) eta bere ibilbide-planarekin: geldialdiak ordu programatuarekin eta aurreikusiarekin (ordutegia gehi uneko atzerapena).

Cachea: 5 s · Probatu

{
  "id": "renfe_ld:00297",
  "properties": { "…": "como en /trains" },
  "track": [[-3.6893, 40.4066, 1793520736]],
  "itinerary": {
    "method": "horario_mas_retraso_actual",
    "delay_s": 180,
    "stops": [{
      "code": "71801", "name": "Barcelona-Sants",
      "arrival_ts": 1793530800, "estimated_arrival_ts": 1793530980,
      "state": "upcoming"
    }]
  }
}

GET/api/v1/trains/numero/{número}

/trains/{id}-ren gauza bera, txartelean edo panelean agertzen den zenbaki komertzialaren bidez bilatuta. 404 erantzuten du zenbaki horrek orain kokapenik ez badu.

Cachea: 5 s · Probatu

{ "id": "renfe_cercanias:1004D27704C5", "properties": { "…": "…" }, "track": [], "itinerary": null }

GET/api/v1/horario/numero/{número}

Tren-zenbaki baten gaurko irteerak, Renferen GTFS egutegiaren arabera, bere geldialdiekin eta bertan behera utzita dagoen ala ez. Oraindik irten ez diren trenetarako balio du.

Cachea: 30 s · Probatu

{
  "method": "horario_gtfs",
  "runs": [{
    "trip_id": "0029712026-11-01", "day": "2026-11-01", "cancelled": false,
    "product": "AVE", "origin": "Madrid-Puerta de Atocha", "destination": "Barcelona-Sants",
    "departure_ts": 1793520000, "arrival_ts": 1793530800,
    "itinerary": { "stops": [] }
  }]
}

GET/api/v1/stations/{código}

Geltoki batean hurrengo bi orduetako trenak: zirkulatzen ari direnak, aurreikusitako orduarekin, eta gaurko ordutegiaren arabera oraindik irten ez direnak (state: scheduled). Geltokiaren fitxa ere badakar, Adif-ek argitaratzen duenean.

Cachea: 10 s · Probatu

{
  "station": { "code": "18000", "name": "Madrid-Puerta de Atocha", "lat": 40.4066, "lon": -3.6893 },
  "trains": [{
    "id": null, "trip_id": "…", "state": "scheduled", "category": "cercanias",
    "product": "C5", "train_number": "27704", "destination": "Humanes",
    "planned_ts": 1793520660, "estimated_ts": null, "delay_s": null,
    "cancelled": false, "terminates": false
  }]
}

GET/api/v1/stations

Geltoki guztiak beren kodearekin eta izenarekin, puntuen GeoJSON gisa.

Cachea: 1 h, ETag · Probatu

{ "type": "FeatureCollection", "features": [{ "geometry": { "type": "Point", "coordinates": [-3.6893, 40.4066] }, "properties": { "code": "18000", "name": "Madrid-Puerta de Atocha" } }] }

GET/api/v1/lines

Cercanías, FGC eta Metro Bilbaoren lineen ibilbidea, beren kolorearekin, 15 m inguruko zehaztasunera sinplifikatutako lineen GeoJSON gisa.

Cachea: 1 h, ETag · Probatu

{ "type": "FeatureCollection", "features": [{ "properties": { "nucleo": "Madrid", "line": "C5", "name": "Móstoles-El Soto - Humanes", "color": "#FFCB06", "text_color": "#000000" }, "geometry": { "type": "LineString", "coordinates": [] } }] }

GET/api/v1/puntualidad

Eguneko puntualtasuna linea eta produktuaren arabera: bidaiak, atzerapena izan duten bidaiak eta atzerapenen batura, tren bakoitzaren azken atzerapen argitaratutik abiatuta.

Cachea: 5 min · Probatu

{ "on_time_threshold_s": 300, "days": [{ "date": "2026-10-31", "partial": false, "groups": [{ "label": "C5", "nucleo": "Madrid", "trips": 412, "on_time": 371, "over_30": 2 }] }] }

GET/api/v1/alerts

Renfek argitaratutako Cercanías-eko abisu aktiboak, eragiten dieten lineekin.

Cachea: 30 s · Probatu

{ "alerts": [{ "id": "…", "text": "…", "start": "2026-11-01T05:00:00Z", "end": null, "lines": [{ "nucleo": "Madrid", "line": "C3" }] }] }

GET/api/v1/cancellations

Renfek une honetan bertan behera utzitzat ematen dituen trenak.

Cachea: 30 s · Probatu

{ "count": 1, "trains": [{ "trip_id": "…", "category": "md", "product": "MD", "train_number": "18073", "origin": "…", "destination": "…" }] }

GET/api/v1/status

Zerbitzuaren laburpena: tren kopurua, uneko puntualtasuna eta iturri bakoitzaren osasuna.

Cachea: 10 s · Probatu

{ "trains": { "total": 812, "fresh": 790, "by_category": { "ld": 120, "cercanias": 610 } }, "delay": { "known": 700, "on_time_share": 0.91 }, "cancelled": 11, "feeds": [{ "id": "renfe_ld_positions", "ok": true, "data_age_s": 14 }] }

JavaScript, nabigatzailean edo Node 18+ bertsioan:

const res = await fetch("https://trenes.valfiguer.com/api/v1/trains");
const { features } = await res.json();
const late = features.filter((f) => (f.properties.delay_s ?? 0) > 600);
console.log(`${late.length} tren 10 min baino gehiagoko atzerapenarekin`);

Python:

import httpx

board = httpx.get("https://trenes.valfiguer.com/api/v1/stations/18000").json()
for t in board["trains"][:5]:
    print(t["product"], t["destination"], t["delay_s"])

Mapa MapLibre edo Leaflet-ekin: gehitu /trains-en erantzuna GeoJSON iturri gisa eta freskatu 15 s-tik behin.

map.addSource("trenes", { type: "geojson", data: "https://trenes.valfiguer.com/api/v1/trains" });
setInterval(() => map.getSource("trenes").setData("https://trenes.valfiguer.com/api/v1/trains"), 15000);

v1 egonkorra da: eremuak gehi ditzakegu, baina ez ditugu kenduko edo haien esanahia aldatuko v2 bat argitaratu eta v1 gutxienez sei hilabetez mantendu gabe. Zure kodeak ezagutzen ez dituen eremuak ez ikusi egin behar ditu.

Iturriei, haien maiztasunari eta erregistro historikoari buruz gehiago, Datuak orrian.

Geltoki baten irteera-panela edo linea baten trenak, zure orriaren barruan. Beren kabuz eguneratzen dira eta edukira egokitzen dute altuera. Itsatsi blokea agertzea nahi duzun lekuan:

<div data-trenes-estacion="18000"></div>
<script src="https://trenes.valfiguer.com/embed.js" async></script>

Linea bat: sarea eta linea, mapan agertzen diren bezala, minuskulaz eta marratxoekin.

<div data-trenes-linea="madrid/c5"></div>
<div data-trenes-linea="rodalies-de-catalunya/r2-nord"></div>
<div data-trenes-linea="fgc/s1"></div>
<script src="https://trenes.valfiguer.com/embed.js" async></script>

• data-tema="claro" (argia) edo "oscuro" (iluna): gaia finkatzen du. Hura gabe, bisitariarena jarraitzen du. Atributua eta haren balioak gaztelaniaz geratzen dira.
• data-filas="6": zenbat tren erakutsi (geltokia: 1–15, 6 lehenespenez; linea: 1–20, 8 lehenespenez).
• data-idioma="eu": widgetaren hizkuntza (es, en, ca, eu edo gl; gaztelania lehenespenez). Panela eta hasierako pantailako widgeta ere hizkuntza bakoitzean daude: /eu/panel/18000.
• Geltoki-kodea Renferena da, /stations/{código} bidean eta geltoki-orri bakoitzaren helbidean dagoen bera.
• Orria kargatu ondoren widgetak gehitzen badituzu (orri bakarreko aplikazio bat), deitu window.TrenesEmbed.scan() funtzioari.

JavaScript gabe, altuera finkoko iframe batekin:

<iframe src="https://trenes.valfiguer.com/embed/estacion/18000?tema=claro&filas=5"
        title="Hurrengo trenak" loading="lazy"
        style="width:100%;height:360px;border:0"></iframe>

Widgetaren oinean lizentziek eskatzen duten aitortza (Renfe Data, FGC eta MovEuskadi, CC BY 4.0) eta orri osorako esteka bat daude: ez estali eta ez kendu. /embed/ bideak soilik erakus daitezke beste webgune batzuen barruan.

Ataritegi, bulego edo kafetegi bateko telebista edo tableta baterako: /panel/{código} bideak hurrengo irteerak letra handiz erakusten ditu, erlojuarekin; 15 s-tik behin eguneratzen da, letra-tamaina pantailara egokitzen du eta, nabigatzaileak uzten duen lekuan, pantaila itzaltzea eragozten du.

https://trenes.valfiguer.com/panel/18000
https://trenes.valfiguer.com/panel/18000?tema=claro&filas=8

Iluna lehenespenez; ?tema=claro (argia) argi handiko geletarako. ?filas= parametroak 3tik 20ra onartzen ditu. Geltoki-orri bakoitzak «Panel modua» esteka bat du.

Modulu txiki bat, mendekotasunik gabe, nabigatzailerako edo Node 18+ bertsiorako. Motak /sdk/trenes.d.ts fitxategian.

import { createClient } from "https://trenes.valfiguer.com/sdk/trenes.js";

const api = createClient(); // edo createClient({ baseUrl, timeoutMs, fetch })
const { features } = await api.trains();
const board = await api.station("18000"); // null kodea existitzen ez bada
const runs = await api.schedule("00297");
const tren = await api.train(features[0].id);
const lineas = await api.lines();

Funtzio bakoitza bereiz ere esportatzen du (trains, train, station, schedule, lines…). 404 batek null itzultzen du; beste edozein errorek TrenesError jaurtitzen du, bere status balioarekin. TypeScript-erako, deskargatu .d.ts fitxategia moduluaren ondoan edo kopiatu behar dituzun motak.

Python 3.10+, liburutegi estandarrarekin soilik:

import json
import urllib.request

BASE = "https://trenes.valfiguer.com/api/v1"

def get(path: str):
    req = urllib.request.Request(BASE + path, headers={"Accept": "application/json"})
    with urllib.request.urlopen(req, timeout=10) as res:
        return json.load(res)

board = get("/stations/18000")
print(board["station"]["name"])
for t in board["trains"][:8]:
    atzerapena = "daturik ez" if t["delay_s"] is None else f"{round(t['delay_s'] / 60)} min"
    print(t["product"], t["train_number"], "→", t["destination"], atzerapena)

# Datuak: Renfe Data, FGC eta MovEuskadi (CC BY 4.0), trenes.valfiguer.com bidez

Abisuak eta bertan behera uzteak RSS formatuan, zure albiste-irakurlerako edo alertak automatizatzeko. Sarearen eta linearen arabera iragaz daitezke ?nucleo=madrid&linea=c5 erabiliz; linea-orri bakoitzak bereak estekatzen ditu.

• /api/v1/feeds/avisos.xml: Cercanías eta Rodalies-eko abisu aktiboak.
• /api/v1/feeds/cancelaciones.xml: Renfek une honetan bertan behera utzitzat markatzen dituen trenak.

Renfek bere datu irekietan argitaratzen duena islatzen dute, hutsune berberekin. CC BY 4.0 lizentzia. Abisuen testuak gaztelaniaz daude, Renfek argitaratzen dituen bezala.