JSON feed

Dagelijks Woord biedt een JSON feed voor developers. De meeste RESTful systemen kunnen met deze feed omgaan.

Opbouw JSON feed versie 1.0

De JSON feed bevat op het hoogste niveau de volgende sleutels:

  • _readme – Deze sleutel bevat informatie voor ontwikkelaars.
  • copyrights – Deze sleutel bevat een associative array van de copyright-teksten voor elke vertaling zoals deze is aangeboden door de copyright-houder. Vermelding van de copyright-tekst is door de copyright-houder verplicht gesteld, al zijn er geen richtlijnen over hoe de vermelding moet plaatsvinden. Dat mag dus ook klein onderaan de pagina.
  • data – Deze sleutel bevat de feitelijke inhoud.
  • debug_info – Deze sleutel bevat informatie voor debugging en is voor eindgebruikers niet interessant.
  • translations – Een associative array met de beschikbare vertalingen. De key is de vertalings-code, de value is wat bezoekers zouden kunnen zien.

De data-sleutel is opgebouwd als een numbered array van associative arrays. De associative array is opgebouwd als volgt:

  • fulltext – Link naar het vers in context. Wilt u vanaf uw website linken naar de bijbel? Gebruik dan deze link.
  • source – vers-verwijzing
  • text – associative array met vertaling-code=>bijbeltekst. De bijbeltekst is utf-8 encoded om letters met accenten mogelijk te maken.
  • ts – timestamp – datum van de tekst
  • wpId -> Dagelijks Woord intern tekst-ID

Voorbeeld-feed

{
    "copyrights": {
        "hsv": "De bijbeltekst in deze uitgave is ontleend aan de Bijbel in de Herziene Statenvertaling, (C) Stichting HSV 2010. Alle rechten voorbehouden, (C) Stichting HSV en Uitgeverij Jongbloed - Heerenveen.",
    },
    "data": [
        {
            "fulltext": "http://www.dagelijkswoord.nl/bijbel/2+Korintiers+1%3A5",
            "source": "2 Korintiers 1:5",
            "text": {
                "hsv": "Want zoals het lijden van Christus overvloedig over ons komt, zo is door Christus ook onze vertroosting overvloedig.",
            },
            "ts": "2015-06-01",
            "wpId": "4209"
        },
        [...knip...]
    ],
    "translations": {
        "hsv": "Herziene Statenvertaling",
    }
}

URL

https://feed.dagelijkswoord.nl/api/json/1.0/

API Key aanvragen

Voor toegang tot deze JSON feed is Basic HTTP-authenticatie vereist. U kunt hier toegang aanvragen:

In verband met misbruik door spambots is het enkele dagen niet mogelijk een key aan te vragen. We hopen binnenkort een captcha te plaatsen om dit formulier te beschermen.

Toch toegang? Vul even het contactformulier in, we helpen u graag.

Uw e-mail adres wordt alleen gebruikt om u te informeren over de JSON-feed. Bijvoorbeeld wanneer een nieuwe versie beschikbaar komt, wanneer nieuwe velden worden toegevoegd, wanneer een URL wijzigt of we merken dat uw koppeling de dienst overbelast.

De key is per ontwikkelteam, niet per eindgebruiker of per toepassing. De key geeft geen bijzondere toegang, u kunt de key dus veilig hardcoded in een applicatie stoppen. De key heeft geen verloopdatum en hoeft dus niet vernieuwd te worden.

Caching

Dagelijks Woord gebruikt diverse methodes om de JSON-feed snel te maken. Maar echte snelheidswinst komt uit het niet onnodig downloaden van de JSON-feed. De feed zal nooit meer dan 1x per dag wijzigen. Bewaart u daarom de feed in het cache-geheugen van uw applicatie om vertraging te voorkomen.

Voorbeeld PHP code

function dagelijkswoord(){
    $username="uw@email-invullen";
    $password="api-key-hier-invullen";
    $cachefile=dirname(__FILE__).'/dagelijkswoord-cache.json';
    $cacheseconds=3600; // 1 uur cache
    if(file_exists($cachefile) && (time()-filemtime($cachefile)< $cacheseconds)){
          $data=json_decode(file_get_contents($cachefile),true);
          if(is_array($data)) return $data;
    }
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "https://feed.dagelijkswoord.nl/api/json/1.0/");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 2); //Maximaal 2 seconden wachten op connectie
    curl_setopt($ch, CURLOPT_TIMEOUT, 10); //Maximaal 10 seconden wachten op ophalen
    curl_setopt($ch, CURLOPT_USERPWD, $username . ":" . $password);  
    $result = curl_exec($ch);
    file_put_contents($cachefile,$result);
    curl_close($ch);
    return json_decode($result,true);
}

Gebruik via Javascript/jQuery

Wil je deze feed gebruiken in je eigen Javascript/jQuery programma, maak dan gebruik van een PHP-proxy op je eigen site. Bijvoorbeeld:

$username="uw@email-invullen";
$password="api-key-hier-invullen";
$cachefile=dirname(__FILE__).'/dagelijkswoord-cache.json';
$cacheseconds=3600; // 1 uur cache
if(file_exists($cachefile) && (time()-filemtime($cachefile)< $cacheseconds)){
      $result=file_get_contents($cachefile);
}else{
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "https://feed.dagelijkswoord.nl/api/json/1.0/");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 2); //Maximaal 2 seconden wachten op connectie
    curl_setopt($ch, CURLOPT_TIMEOUT, 10); //Maximaal 10 seconden wachten op ophalen
    curl_setopt($ch, CURLOPT_USERPWD, $username . ":" . $password);  
    $result = curl_exec($ch);
    file_put_contents($cachefile,$result);
    curl_close($ch);
}
header('Content-Type: application/json');
echo $result;

Dit heeft met name voordelen voor de performance. Ook helpt dit oudere browsers, die nog geen CORS-ondersteuning hebben, de gegegevens toch goed te laden.

Kosten

Gebruik van de JSON feed is gratis. Een vrijwillige bijdrage wordt op prijs gesteld.

Gebruik van de content

U mag de content gebruiken op een website of voor interne applicaties van uw werk of kerk. Het herpubliceren binnen een mobiele app of feed is niet toegestaan.