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 [email protected]. 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, [email protected], 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
            firstName
            lastName
          }
        }

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

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

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

{
          "data": {
            "speakers": [
              {
                "id": "244",
                "firstName": "Miloš",
                "lastName": "Vystrčil"
              },
              {
                "id": "168",
                "firstName": "Miloš",
                "lastName": "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
            firstName
            lastName
            body {
              shortName
              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
            excerptedAt
            content
            assessment {
              veracity {
                name
              }
              shortExplanation
              explanationHtml
            }
          }
        }

Abychom mohli měřit návštěvnost webu, potřebujeme Váš souhlas se zpracováním osobních údajů prostřednictvím cookies. Více o zpracování osobních údajů