JSON feed

Dagelijks Woord biedt een JSON feed voor developers.

Opbouw JSON feed versie 1.0

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

  • 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.
  • strings – Deze sleutel bevat extra string-informatie.
  • 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
  • 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

http://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:

E-mail:
Sta @ in gebruikersnaam toe?
Commentaar:Zou u ons willen vertellen hoe u de API wilt gaan inzetten? (optioneel)

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.

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, "http://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, "http://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, maar is absoluut niet verplicht.