Práce s Sklik API Vyhledávání
Všechno důležité dění okolo API. Odebírej náš Sklik API newsletter.

Aktuálně dostupné verze Sklik API

Naše rozhraní Sklik API je aktuálně dostupné v těchto verzích:

  • Sklik API Cipisek – Historicky třetí generace rozhraní. Rozhraní nenabízí tolik možností jako nové API Drak, nebudeme jej dále rozvíjet a aktuálně připravujeme její ukončení (plánované na 15. ledna 2019)
  • Sklik API Drak – V současné době preferované a podporované rozhraní. Je možné jej používat pomoci protokolu XML-RPC a JSON.
Doporučujeme používat API Drak a JSON protokol.

Dostupné třídy metod API Sklik Drak

  • Ads – Správa reklam a jejich přehledy.
  • Api – Informace o aktuálně používané verzi API.
  • Autotagging – Nastavení automatického tagování proklikové URL o informace o zdroji reklamy.
  • Banners [Obsahová síť] – Správa bannerů a jejich přehledy.
  • Campaigns – Správa kampaní a jejich přehledy.
  • Client – Informace o uživateli, včetně účtů, které spravuje.
  • Contextnetwork [Obsahová síť] – Obsahové sítě (CZ, SK).
  • Conversions – Správa konverzních kódů.
  • Group – Správa sestav a jejich přehledy.
  • Images – Správa obrázku (pro použití v bannerech nebo kombinované reklamě).
  • Intends[Sestava|Obsahová síť] – Správa zájmů o koupi včetně vyloučení a jejich přehledy.
  • Interests[Sestava|Obsahová síť] – Správa zájmů včetně vyloučení a jejich přehledy.
  • Keywords – Správa klíčových slov včetně vylučujících a jejich přehledy.
  • Partner – Správa inzerentských ploch (určeno pro členy Seznam.cz Partner).
  • Patterns [Sestava|Obsahová síť] – Správa umístění reklamy v obsahové síti.
  • Productsets – Přehledy produktových skupin (v rámci produktových kampaní).
  • Queries[Vyhledávací síť] – Přehledy vyhledávacích dotazů.
  • Retargeting – Nastavení retargetingu.
  • Sharedbudgets – Správa sdíleného rozpočtu.
  • Sitelinks[Vyhledávací síť] – Správa Sklik Odkazů s jejich přehledy.
  • Themes [Sestava|Obsahová síť] – Nastavení zobrazování na tematických webech.

Základní metody

  • create – Vytvoření nové entity.
  • check – Identická struktura jako metoda create. Je možné si ověřit, že bude vytvořeno vše v pořádku.
  • remove – Smazání entity.
  • restore – Obnovení smazané entity do stavu před smazání. Pokud byla entita pozastavena, restore tento status nezmění.
  • update – Upravuje parametry entity. Pokud jde o změnu samotného obsahu reklam, update ji neupraví, ale vytvoří novou entitu (a původní smažou). Nová entita prochází stejným schvalovacím procesem jako při nově vytvořené.
  • createReport – První část dvoufázového čtení reportů. Zde definujete výběr dat.
  • readReport – Samotné čtení reportů, musí následovat po createReport.

Emailový newsletter

Důležité novinky o Sklik API

O všech důležitých událostech (výpadcích, změnách nebo připravovaných novinkách) nyní budeme informovat i prostřednictvím Sklik API newsletteru. Stačí zanechat e-mail a nic důležitého vám neuteče.


Přihlášením k odběru novinek nám udělujete souhlas se zpracováním osobních údajů.

Znalostí báze

Changelog

Připravili jsme pro vás veřejný changelog. V něm naleznete všechny provedené změny na rozhraní, včetně oprav chyb a přidávání nových funkcí.
Dodržujeme verzovací standard Major.Minor.Patch.
Changelog

Statusy entit

Oproti zobrazení statusu na webovém rozhraní, je status (aktivní, pozastavená, smazaná) přiřazen pouze dané entitě. Ovšem vliv má na všechny nižší entity pod ní spadající.
Například pokud pozastavíte vybranou kampaň (změníte status u kampaně jako pozastavená), všechny sestavy i reklamy si zachovají původní status, ale zároveň respektují status nadřazené entity – kampaně. Proto se všechny reklamy v dané kampani chovají jako pozastavené a nebudou se zobrazovat. Při dotazu pomocí API vám však budou hlásit, že mají status aktivní.

Práce s časem

Rozhraní využívá pro parametry data standardní formát datetime. Ten nabízí možnost zadávat nejen datum, ale i konkrétní čas.
Obecně se dá říct, že vynecháním času ve struktuře datetime nic nezkazíte. I na webovém rozhraní lze pracovat pouze s přesností na dny a je to nejnižší granularita, kterou v práci s účty garantujeme.

    • Datetime u createReportu vrací statistiky vždy za celý den. Zahrnují oba dny, které nastavují rozmezí.
Při nastavení dateFrom 1. 1. 2017 a dateTo 10. 1. 2017 dostanete statistický přehled prokliků včetně těch, které byly uskutečněny jak 1. 1., tak 10. 1.
    • Datetime u nastavení začátku a konce kampaní je naopak možné naplánovat na minutu přesně, tuto přesnost však nijak negarantujeme. Jak se kampaně chovají při nastavení pouze datumu: v nastavený den se kampaň spustí i ukončí na začátku dne (o půlnoci).
Pokud si přejete, aby se kampaň spustila 10. 1. a běžela hned od začátku dne, pak parametr startDate nastavte na 10. 1. naopak pokud chcete, aby kampaň běžela do čtvrtka 15. 1. (včetně celého čtvrtka), pak datum konce – endDate nastavte na 16. 1.
{"dateFrom" : datetime.strptime("1.1.2017", "%d.%m.%Y"),
"dateTo" : datetime.strptime("23.11.2018", "%d.%m.%Y")}

Přihlašování a uživatelé

Způsoby přihlášení

API Drak nabízí dva druhy přihlašování. Můžete využít buď klasickou metodu client.login která vyžaduje váš email a heslo, nebo můžete používat API token, pomocí kterého se přihlásíte přes metodu client.loginByToken. API token získáte v rozhraní Sklik.cz v záložce Nastavení účtu.
Oba přístupy jsou rovnocenné. Druhá možnost, přihlášení pomocí tokenu, je ale mnohem bezpečnější. Odděluje přístup k API a vašemu účtu. Umožňuje věnovat přístup k API dalším lidem ve firmě, nebo třetím stranám, aniž byste museli prozrazovat svoje heslo. Je také možné vygenerovat nový token a tím zabránit přístupu všem, kteří nemají token stávající.

p.client.login("email@seznam.cz", 'heslo1234')
p.client.loginByToken("0x577ab56fd48c7...@seznam.cz")

Uživatelé

Než někomu dávat přístupové údaje nebo API klíče, je z důvodu snadné správy přístupů a tím vyšší bezpečnosti vhodnější udělit přístup. Postupujte dle nápovědy. Pro reporting statistik bez možnosti cokoliv měnit je vhodný přístup Reportér statistik. Pokud je třeba přes API kampaně upravovat nebo jakékoliv položky v účtu přidávat, je potřeba aby měl uživatel schválený přístup na úrovni Správce kampaní.
Uživatel s přiděleným přístupem se do API přihlásí pomocí svých přístupových údajů. Aby mohl editovat a pracovat s vaším účtem, musí při volání každé metody vkládat parametr user.userId (ID vašeho účtu). Pokud nebude tento parametr vyplněn, bude API přistupovat k aktuálně přihlášenému účtu, i když v něm nebudou žádné kampaně.

Získání userId

Metoda client.get vrací všechny informace o vlastním účtu i účtech spojených s ním. Reponse vrací ID vlastního účtu user.userId a ID všech spojených účtů foreignAccounts[].userId

Reporty

O získávání veškerých statistik účtu se stará dvojice metod createReport a readReport. Více o práci s reporty zjistíte na našem Seznam blogu

createReport

Vytvoří přehled dat, které je s pomocí návratové hodnoty reportId možné číst readReportem. Přehled je po vytvoření dále neměnný a zachovává se u něj pořadí dat.

Příklad createReportu a odpovědi server

 p.campaigns.createReport({'session': '10XEBV...AzNWM=', 'userId': 11111},{
                "statisticsConditions": [{
                       "columnName":"clicks",
                       "operator": "GT",
                       "intValue": 10
                }],
                "dateFrom": datetime.strptime("01.05.2018", "%d.%m.%Y"),
                "dateTo": datetime.strptime("31.05.2018", "%d.%m.%Y")
        })

 

{'status': 200, 'totalCount': 19, 'session': '10XEP...NWM=', 'reportId': 'bqr...cmVv)75ed284', 'statusMessage': 'OK'}

readReport

Slouží ke čtení vytvořeného přehledu (createReport). Parametry je možné pouze omezit data (sloupce, řádky), ale není možné provádět žádné filtry jako omezení podle kampaní, hodnoty dat a jiné. Výjimkou je allowEmptyRows, která vynechává nulové záznamy (toto vynechávání je defaultně povoleno).

Stránkování

U reportů často nastává situace, že záznamů je velké množství. Aby nedošlo k přetížení sítě, je server nastaven na omezené množství přenesených dat. Tento limit serveru zjistíte jako chybovou návratovou hodnotu u chyby typu 413, která se vrátí, pokud tento limit překročíte. Standardně u reportů je nastavena na hodnotě 5 tisíc řádků.

p.campaigns.readReport({'session': '10XEBV...AzNWM=', 'userId':11111},'bqr...cmVv)75ed284', {
                        "offset":0, 
                        "limit":1000, 
                        "allowEmptyStatistics": False,                        
                        "displayColumns": ["name",'totalMoney', 'clickMoney', 'totalClicks', 'impressions', 'clicks']
                })

Jak stránkovat?

Pro stránkování slouží parametry limitoffset (stejné vlastnosti jako SQL dotazy). Limit udává maximální množství záznamů, které chcete získat. Hodnotu můžete nastavit libovolně, pouze vrchní hranice je určena serverem (viz výše).
Offset slouží jako stránkovač. Hodnota říká, od jakého záznamu chceme záznamy číst.

createReport vytvořil přehled o 10 521 záznamů (totalCount). Maximum přenosu je nastaveno na 5 000 záznamů, proto přečtení všech záznamů lze jedině pomoci stránkování.
Budeme tedy volat 3x readReport. Prvním voláním chceme přečíst prvních 5 000 záznamů, takže musíme mít nastavený limit na 5 000 a offset od nultého řádku 0.
Druhé volání má číst 5 001 – 10 000. Posunem offset na 5 000, aby se četlo právě 5 000 řádků od 5 001 záznamu.
Pro třetí volání nám už zbývá 521 záznamů. Posuneme offset na 10 000 a limit můžeme nastavit na 521 – nebo ponechat na 5 000 (server čte do konce záznamů, nebo po limit).

Granularita

Limit ovlivňuje i granularita (výpis dat po dnech, týdnech, měsících, kvartálech a rocích). V takovém případě je maximální limit podílem počtem dnů.

Pokud v createReportu zadám rozpad po dnech a žádám o záznam za posledních 50 dní, pak limit, který musím nastavit, vypočítám jako 5 000/50 a nastavím limit 100
p.campaigns.createReport({'session': '10XEBV...AzNWM=', 'userId': 11111},{                
                'dateFrom': datetime.strptime("01.05.2018", "%d.%m.%Y"),
                'dateTo': datetime.strptime("31.05.2018", "%d.%m.%Y") 
                },
                {'statGranularity': 'daily'}
        )

parametr allowEmptyStatistics

Výstupy může značně ovlivnit parametr allowEmptyStatistics. Ten je v základu nastaven na hodnotě false. To znamená, že při posílání záznamů server vynechává nulové řádky. Avšak při počítání limitů a offsetů se tyto nulové záznamy započítávají, jen se neposílají uživateli. Proto může nastat situace, že při nastavení limitu 200, server vrátí jenom 150 záznamů. 50 chybějících jsou nevypsané nulové záznamy.

Více o přístupu ke statistikám na našem blogu – Jak správně používat limit a offset v metodách pro statistické reporty v API Drak

Propojení s Firmy.cz

Nastavení spojení

Stejně jako v rozhraní Skliku je možné i prostřednictvím API propojit kampaně s Firmy.cz (a následně i jednotlivé inzeráty). Rozšíření inzerátu o adresu

Spojení s Firmy.cz je potřeba nejdříve nastavit na úrovni kampaně. V metodě campaigns.create v poli campaigns je třeba vyplnit strukturu premise.

ID – ID dle katalogu Firmy.cz. Toto ID lze zjisti například z URL adresy vaší firmy. Pro firmu Seznam.cz je ID 155088. Její URL adresa je – https://www.firmy.cz/detail/155088-seznam-cz-praha-smichov.html

Nastavení jednotlivých poboček lze nastavit buď jako defaultId taktéž v campaigns.create, nebo pak až na úrovni vytváření reklam v metodě ads.create kde v poli ads je třeba vyplnit premiseId.

Opět zde zadáváte ID jednotlivých poboček. Toto id zjistíte stejně jako id celé firmy. Stačí si kliknout na seznam poboček a podívat se na její URL. Brněnská pobočka Seznam.cz má ID 429645 a její URL je https://www.firmy.cz/detail/429645-seznam-cz-brno-styrice.html

p.campaigns.create({'session': '10XEBV...AzNWM=', 'userId': 11111}
    [{'status': 'active', 
        'dayBudget': 3000, 
        'name': 'Name of new campaigns2', 
        'targetDevices': {'mobile': True, 'other': True, 'tablet': True, 'desktop': True},
        'type': 'fulltext',
        'adSelection': 'weighted',
        'premise': {
                'id': 155088,
                'defaultMode': 'one',
                'defaultId': 429645
                }
        }])

p.ads.create({'session': '10XEBV...AzNWM=', 'userId': 11111}
        [{
                'adType':'eta',
                'headline1': 'Text of headline1',
                'headline2': 'Text of headline2',
                'description': 'Some description',
                'finalUrl':'http://www.napoveda.sklik.cz',
                'premiseMode':'one',        
                'premiseId': 429645,        
                'groupId': 78288473,
        }])

Kontaktování technické podpory

Pokud jste narazili na nějaký problém, který se vám nedaří odstranit, doporučujeme kontaktovat naši podporu. Prosíme vás vždy o přiložení základních informací, které s problémy kolem API potřebujeme:

    • ID (nebo e-mail) účtu, se kterým pracujete.
    • Požadavek na server
    • Odpověď serveru
    • Čas – čím přesnější čas výskytu situace zašlete, tím spíše usnadníte její rychlé vyřešení.