Evangelieboken

API – dokumentation

Vad är API:t?

API:t gör det möjligt för andra webbplatser, appar och program att hämta information från evangelieboken.se automatiskt. Du kan till exempel visa nästa helgdag på en församlings webbplats eller bygga en egen kalender med kyrkoårets helgdagar och bibelreferenser. API:t tillhandahåller kyrkoårets referenser. Läsplans-API:t returnerar referenser och metadata, aldrig bibeltext. Parametern include_texts ignoreras. På webbplatsen kan besökaren välja Bibel 2000, Bibel 2026 eller Kyrkobibeln 1917 för läsning på Bibeln.se.

Visa nästa helgdag på din webbplats

Här är ett exempel på hur du kan visa information om nästkommande helgdag på din webbplats. API-anropet GET /api/v1/holidays/next ger en respons som kan se ut så här:

Hämtar ett aktuellt svar. Tills dess visas ett statiskt exempel.

{
  "id": 31,
  "date": "2026-04-05",
  "name": "Påskdagen",
  "slug": "paskdagen",
  "rubric": "Kristus är uppstånden",
  "reading_label": "Första årgången",
  "readings": {
    "gt": "Hos 6:1–3",
    "epistel": "1 Kor 15:1–11",
    "evangelium": "Mark 16:1–8",
    "psaltaren": "Ps 118:15–24"
  }
}

Du kan sedan använda informationen på din egen webbplats, i din app eller i ett annat program.

Exempel med JavaScript:

<div id="next-holiday" role="status">Hämtar helgdagen…</div>

<script type="module">
const output = document.querySelector('#next-holiday');
try {
  // Ange API-värden för den webbplats som tillhandahåller tjänsten.
  const response = await fetch('https://evangelieboken.se/api/v1/holidays/next');
  if (!response.ok) throw new Error('API-anropet misslyckades.');
  const holiday = await response.json();
  output.textContent = holiday.name;
} catch {
  output.textContent = 'Helgdagen kunde inte hämtas. Försök igen senare.';
}
</script>

Giltiga datum och fel

Giltigt datumintervall är 2003-11-30–2099-12-31, inklusive båda dagarna. Startdatumet är första advent 2003, då denna version av evangelieboken började gälla. Ange datum som YYYY-MM-DD.

Ogiltiga datum och år ger HTTP 400 med ett JSON-fel som anger datumintervallet. PDF och ICS genereras då inte. Om datumet är giltigt men ingen kommande helgdag finns inom intervallet ger datumuppslag HTTP 404. ICS ger HTTP 400 om datumet saknar en helgdag.

{"error":"Ange ett giltigt datum mellan 2003-11-30 och 2099-12-31 på formen ÅÅÅÅ-MM-DD. Evangelieboken började gälla första advent 2003."}

PDF och ICS för hela kalenderår eller kyrkoår stöder år 2004–2099. Kyrkoår anges med slutåret: church_year=2004 börjar 2003-11-30. Hela kalenderåret 2003 och kyrkoåret 2100 ligger delvis utanför intervallet och kan inte exporteras. Välj ett enskilt giltigt helgdagsdatum i stället. Ange endast ett periodval: date, year, church_year eller, för en helgdags-PDF, all_years=true; värdet ska vara en enkel sträng, inte en array.

Några exempel

  • Visa nästa helgdag: GET /api/v1/holidays/next
  • Hämta en viss dag: GET /api/v1/holidays/{YYYY-MM-DD}
  • Hämta alla helgdagar för ett kyrkoår (ange slutåret): GET /api/v1/holidays?year={YYYY}
  • Söka efter en helgdag: GET /api/v1/holidays?search=advent
  • Hämta kalenderfil för ett år: GET /api/v1/ics?year={YYYY}
  • Hämta PDF-dokument med översikt över årets alla helgdagar: GET /api/v1/pdf/holidays?year={YYYY}&content=references
Se alla API-metoder
  • Helgdagar (Holidays)

    Hämtar information om kyrkoårets helgdagar, datum, tema och läsningar (bibelreferenser).

    • GET /api/v1/holidays?year={YYYY}

      Hämtar helgdagarna för ett kyrkoår, angivet med slutåret (2004–2100). Svaret ges i datumordning och innehåller endast datum inom 2003-11-30–2099-12-31. År 2100 ger därför bara helgdagar från slutet av 2099.

    • GET /api/v1/holidays?name={namn}

      Söker efter en helgdag via dess namn (delvis matchning stöds) och returnerar dess nästkommande instans.

    • GET /api/v1/holidays?search={query}

      Fritextsökning efter en helgdag (t.ex. baserat på innehåll/bibelord) och returnerar nästkommande instans av matchande helgdagar.

    • GET /api/v1/holidays/next

      Returnerar den allra närmast kommande helgdagen efter (inklusive) dagens datum.

    • GET /api/v1/holidays/{YYYY-MM-DD}

      Returnerar den helgdag som infaller på, eller närmast efter, det angivna datumet.

    • GET /api/v1/holidays/{slug}

      Hämtar nästkommande instans av en specifik helgdag identifierad med sin URL-vänliga slug (t.ex. annandag-pask).

    • Globala parametrar för Helgdagar (valfria):
      • include_all_years=true: Inkluderar läsningar för alla årgångar istället för bara den aktuella.
  • Kalender / ICS-export

    Används för att exportera helgdagar till iCalendar-format (.ics) för import till kalenderprogram.

    • GET /api/v1/ics?date={YYYY-MM-DD}

      Skapar en kalenderfil för den helgdag som infaller på eller närmast efter det angivna datumet.

    • GET /api/v1/ics?year={YYYY}

      Skapar en kalenderfil med alla helgdagar för ett specifikt kalenderår.

    • GET /api/v1/ics?church_year={YYYY}

      Skapar en kalenderfil med alla helgdagar för ett specifikt kyrkoår (börjar Första söndagen i advent i föregående år).

  • PDF-generering

    Endast GET-förfrågningar tillåts. Genererar formaterade PDF-dokument on-the-fly.

    • GET /api/v1/pdf/holidays?year={YYYY}&content=references (eller ?church_year={YYYY}&content=references)

      Genererar ett PDF-dokument med en översikt över alla helgdagar för det angivna kalender- eller kyrkoåret.

    • GET /api/v1/pdf/holiday/{id}?date={YYYY-MM-DD}&content=references

      Genererar en referens-PDF för en enskild helgdag. Använd numeriskt helgdags-ID från JSON-API:t. Datumet måste vara just den helgdagens datum. Utan datum väljs nästa förekomst från idag.

    • GET /api/v1/pdf/holiday/{id}?all_years=true&content=references

      Genererar en referens-PDF för en enskild helgdag med samtliga årgångar eller evangelistserier. Använd numeriskt helgdags-ID.

    • GET /api/v1/pdf/lectionary/{id}?date={YYYY-MM-DD}

      Genererar en PDF med läsplanens läsning för vald dag inför kommande helgdag. Läsplanen anges med id eller slug. En dag utan läsningar ger HTTP 404.

    • GET /api/v1/pdf/lectionary/{id}?year={YYYY} (eller ?church_year={YYYY})

      Genererar ett översiktsdokument i PDF-format för en komplett läsplan under ett visst kalender- eller kyrkoår.

  • Läsplaner (Lectionaries)

    Används för att hämta läsplaner för specifika bibelläsningsserier/böcker.

    • GET /api/v1/lectionaries/readings

      Ord för dagen, med datum i svensk tidszon. Ange ?date=2026-10-05 för ett annat datum. Endast referenser och metadata returneras; include_texts ignoreras. Verserna kan komma från olika årgångar inför kommande helgdag.

      GET /api/v1/lectionaries

      Hämtar en lista med samtliga tillgängliga läsplaner.

    • GET /api/v1/lectionaries/{id}

      Hämtar detaljerad information om en specifik läsplan (baserat på id eller slug) inklusive alla dess definierade läsningar sorterade per helgdag.

    • GET /api/v1/lectionaries/{id}/readings?date={YYYY-MM-DD}

      Hämtar läsningar för en specifik läsplan för den helgdag som inträffar i anslutning till det angivna datumet. Om inget datum anges används dagens datum. Ger även information om kyrkoår, årgång etc.