Demagog.cz

API pro vývojáře

Veškerá zveřejněná data projektu Demagog.cz jsou dostupná i přes API pro zobrazení na jiných serverech či pro zpracování v analýzách. Jde o API rozumějící dotazovacímu jazyku GraphQL a v současné době nevyžaduje autentizaci pro přístup k veřejné části dat a ani neomezuje množství dotazů.

Máme jen jeden požadavek. Plánujete-li data (či analýzu z nich) zobrazovat veřejně, napište nám prosím na info@demagog.cz. Nechceme Vám házet klacky pod nohy, jen nám na formě zveřejnění záleží. Předem děkujeme.

Na stejný email, info@demagog.cz, se nám neváhejte ozvat, pokud budete při použití API potřebovat asistenci.

GraphQL API

GraphQL API je dostupné na adrese https://demagog.cz/graphql a GraphQL dotazy přijímá zabalené v JSON formátu a v HTTP dotazech metody POST. Funguje tedy jako standardní GraphQL API.

Jednoduchý GraphQL dotaz, například na seznam řečníků se jménem Miloš...

{
  speakers(name: "Miloš") {
    id
    first_name
    last_name
  }
}

... by tak pomocí nástroje cURL vypadal následovně:

curl -X POST -H "Content-Type: application/json" --data '{ "query": "{ speakers(name: \"Miloš\") { id first_name last_name } }" }' https://demagog.cz/graphql

API by pak na takový dotaz mělo odpovědět:

{
  "data": {
    "speakers": [
      {
        "id": "244",
        "first_name": "Miloš",
        "last_name": "Vystrčil"
      },
      {
        "id": "168",
        "first_name": "Miloš",
        "last_name": "Zeman"
      }
    ]
  }
}

GraphQL schéma a rozhraní klienta GraphiQL

V příkladu výše si můžete všimnout, že v dotazu jsme se ptali u řečníků pouze na jejich ID (pozn. pouze interní ID pro identifikaci v rámci projektu Demagog.cz), křestní jméno a příjmení. Dat o řečnících máme ale mnohem víc — kromě jiného jejich příslušnost k politickým stranám, adresu profilového obrázku, nebo samozřejmě seznam jejich výroků, které jsme ověřili.

Dotazovací jazyk GraphQL umožňuje zvolit si přesně, o která data máte zájem. A abyste věděli, co je vůbec dostupné, API umí zprostředkovat GraphQL schéma se všemi dostupnými dotazy a parametry. Schéma se vám tedy zobrazí, pokud API otevřete v některém z GraphQL klientů. My vedle API nainstalovali klienta GraphiQL a je to tedy nejjednodušší cesta, jak se ke schématu dostat.

Rozhraní klienta GraphiQL je dostupné na adrese https://demagog.cz/graphiql a schéma zobrazuje v pravém sloupci, který se zobrazí po kliknutí na Docs v pravém horním rohu. Kliknete-li dále na Query, zobrazí se seznam všech dostupných dotazů, jejich možné parametry a typy výsledků. Najdete mezi nimi i dotaz speakers, který jsme použili výše.

Kromě zobrazení schématu lze přes GraphiQL i rovnou posílat dotazy na API a rychle se tak dostat k datům. Neumožňuje ale například export do souboru. Pokud jsou pro vás funkce jako export důležité, můžeme doporučit desktopového GraphQL klienta Altair.

Příklady GraphQL dotazů

Prokousat se schématem dat nemusí být jednoduché, připravili jsme tedy několik příkladů GraphQL dotazů, které se mohou během začátku hodit.

Seznam všech řečníků s příslušností ke straně či hnutí a se statistikami ověřených výroků:

{
  speakers(limit: 1000, offset: 0) {
    id
    first_name
    last_name
    body {
      short_name
      name
    }
    stats {
      true
      untrue
      misleading
      unverifiable
    }
  }
}

Prvních dvacet ověřených výroků prezidenta Miloše Zemana s hodnocením a odůvodněním (168 je naše interní ID, ID jiných řečníků lze najít přes seznam všech řečníků):

{
  statements(speaker: 168, limit: 20, offset: 0) {
    id
    excerpted_at
    content
    assessment {
      veracity {
        name
      }
      short_explanation
      explanation_html
    }
  }
}