API na prístup k dátam kampaní a formátov

INRES poskytuje API na prístup k dátam kampaní a formátov
úroveň prístupu cez API je viazaná na konkrétneho používateľa INRESu - API poskytuje prístup k tým firmám, kampaniam a formátom, ku ktorým má používateľ prístup cez rozhranie INRESu.
API funguje odoslaním HTTP GET požiadavky na URL uvedené nižšie.
API vráti odpoveď v CSV formáte:
- V prípade chyby odpoveď obsahuje len jeden riadok s chybovou správou a http status v odpovedi servera bude iný ako 200.
- V prípade úspešnej API požiadavky server vráti status 200 a požadované údaje v CSV formáte.
- Kódovanie: UTF-8
- Oddeľovač hodnôt na riadku: čiarka ,
- Oddeľovač riadkov: CRLF
- Ak hodnota obsahuje niektoré špeciálne znaky, je uzavretá v úvodzovkách ", napríklad "A, B, C"
- Ak hodnota obsahuje úvodzovky ", tieto sú zdvojené, napríklad
  "A ""B"" C"
  znamená
  A "B" C

Autentifikácia

Na použitie API sú potrebné údaje prístupné na API stránke v INRESe:
- API ID - ID používateľa, ďalej označované aj ako API_ID. Posiela sa v každej API požiadavke ako parameter id.
- API kľúč - "heslo", ďalej označované aj ako API_KEY. Nikdy sa neposiela v API požiadavke priamo, jeho použitie je vysvetlené ďalej.
Každá API požiadavka musí obsahovať parameter id nastavený na API_ID
Každá API požiadavka musí obsahovať parameter auth s autentifikačným hash kódom, ktorý sa vypočíta nasledujúcim spôsobom:
- Na výpočet sa použije tzv. HMAC funkcia:
  - hashovacia funkcia je SHA-256
  - kľúč je API_KEY
    HMAC_SHA256("The quick brown fox jumps over the lazy dog", "key") = f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8 ekvivalentný PHP kód: $auth = hash_hmac('sha256' , 'The quick brown fox jumps over the lazy dog' , 'key');
- hash sa počíta z reťazca tvoreného:
  - textovou reprezentáciou aktuálneho času v tvare UNIX timestamp / 30
  - obsahom všetkých parametrov v lexikografickom (abecednom) poradí
    API URL: https://admin.inres.sk/dataAPI/campaignList?id=QWERTyuiopasdfghjklZXCVB&company=3456 Nech je aktuálny čas 13.8.2018 11:14:44 (stredoeurópsky letný čas). Ekvivalentný UNIX čas (počet sekúnd od začiatku roku 1970) je 1534151684. Po celočíselnom predelení 30 je výsledok 51138389. Reťazec na vstupe HMAC funkcie bude v tomto prípade vyzerať takto: 511383893456QWERTyuiopasdfghjklZXCVB | čas | | id | company (parametre sú v abecednom poradí) Nech API kľúč je MnBvCxyLKJHGfdAs765434qa Potom auth parameter bude: HMAC_SHA256("511383893456QWERTyuiopasdfghjklZXCVB", "MnBvCxyLKJHGfdAs765434qa") = 6452b5e1cfd38a4941a66c8b40415ea4982b981638e6722db2b8e6a6ccd2a71e A potom výsledná url bude: https://admin.inres.sk/dataAPI/campaignList?id=QWERTyuiopasdfghjklZXCVB&company=3456&auth=6452b5e1cfd38a4941a66c8b40415ea4982b981638e6722db2b8e6a6ccd2a71e

API funkcie

Zoznam firiem

URL: https://admin.inres.sk/dataAPI/companyList/
Zoznam firiem, ku ktorým má prístup aktuálny používateľ API
Parametre:
- id (popis vyššie v časti Autentifikácia)
- auth (popis vyššie v časti Autentifikácia)
Výstup: CSV, zoznam firiem:
ID1, Meno1 ID2, Meno2 ...

Príklad Nech API ID je QWERTyuiopasdfghjklZXCVB Nech API kľúč je MnBvCxyLKJHGfdAs765434qa Nech aktuálny čas je 13.8.2018 11:14:44 (stredoeurópsky letný čas). Potom volanie API funkcie a výsledok môže vyzerať takto: curl https://admin.inres.sk/dataAPI/companyList/?id=QWERTyuiopasdfghjklZXCVB&auth=72e8521130e4dc3a5cabdda3334a44fc85a23ddf706e0e6ed4eb2916c2651a7a 3651,Testovacia firma 1 152669,"Testovacia firma 2, s.r.o." 38111,Testovacia firma 3

Zoznam kampaní a formátov

URL: https://admin.inres.sk/dataAPI/campaignList/
Zoznam kampaní (a prípadne formátov), ku ktorým má prístup aktuálny používateľ API
Parametre:
- id (popis vyššie v časti Autentifikácia)
- auth (popis vyššie v časti Autentifikácia)
- company - nepovinný parameter, celočíselné ID firmy. Ak je zadané, funkcia vráti iba kampane tejto firmy. Inak funkcia vráti všetky kampane, ku ktorým má používateľ prístup.
- start - nepovinný parameter, UNIX čas, celé číslo, musí sa použiť spolu s parametrom end
- end - nepovinný parameter, UNIX čas, celé číslo, musí sa použiť spolu s parametrom start. Ak sú zadané parametre start a end, funkcia vráti iba kampane aktívne v časovom intervale ohraničenom zadanými časovými údajmi, inak funkcia vráti všetky kampane.
- formats - nepovinný parameter, ak je nastavený na 1, tak funkcia vráti okrem kampaní aj ich formáty.
Výstup: CSV, zoznam kampaní (parameter formats nie je nastavený):
Campaign,campaign ID 1,campaign Name 1 Campaign,campaign ID 2,campaign Name 2 ...
Výstup: CSV, zoznam kampaní a formátov (parameter formats je nastavený):
Campaign,campaign ID 1,campaign Name 1 Format,format ID 1 1,campaign ID 1 Format,format ID 1 2,campaign ID 1 ... Campaign,campaign ID 2,campaign Name 2 Format,format ID 2 1,campaign ID 2 Format,format ID 2 2,campaign ID 2 ...

Príklad - zoznam všetkých kampaní firmy ID 8965 Nech API ID je QWERTyuiopasdfghjklZXCVB Nech API kľúč je MnBvCxyLKJHGfdAs765434qa Nech aktuálny čas je 13.8.2018 11:14:44 (stredoeurópsky letný čas). Potom volanie API funkcie a výsledok môže vyzerať takto: curl https://admin.inres.sk/dataAPI/campaignList/?id=QWERTyuiopasdfghjklZXCVB&company=8965&auth=e38ffa8bda97ad8eccda0bfe61a9e9c3f8e0828a091d7ee2be4a186da1b5da79 Campaign,958444,Testovacia kampaň 1 Campaign,960000,Testovacia kampaň 2 Campaign,965000,Testovacia kampaň 3

Príklad - zoznam všetkých kampaní a formátov firmy ID 8965 aktívnych v období od 1.5.2018 do 31.5.2018 Nech API ID je QWERTyuiopasdfghjklZXCVB Nech API kľúč je MnBvCxyLKJHGfdAs765434qa Nech aktuálny čas je 13.8.2018 11:14:44 (stredoeurópsky letný čas). Potom volanie API funkcie a výsledok môže vyzerať takto: curl https://admin.inres.sk/dataAPI/campaignList/?id=QWERTyuiopasdfghjklZXCVB&company=8965&start=1525125600&end=1527717600&formats=1&auth=015f2508a28c994f72a201f9e3fdc1d2096398f27849b6d565e55ee5a0711e04 Campaign,958444,Testovacia kampaň 1 Format,11558,958444 Format,11559,958444 Format,11580,958444 Campaign,965000,Testovacia kampaň 3 Format,15667,965000

Štatistika kampane

URL: https://admin.inres.sk/dataAPI/campaign/
Parametre:
- id (popis vyššie v časti Autentifikácia)
- auth (popis vyššie v časti Autentifikácia)
- campId - celočíselné ID kampane
- start - nepovinný parameter, UNIX čas, celé číslo, musí sa použiť spolu s parametrom end
- end - nepovinný parameter, UNIX čas, celé číslo, musí sa použiť spolu s parametrom start. Ak sú zadané parametre start a end, funkcia vráti dennú štatistiku kampane iba v zadanom časovom intervale, inak funkcia vráti všetky denné dáta kampane.
Výstup: CSV, obsahuje 4 časti:
- denné dáta (prípadne ohraničené zadaným intervalom)
- všetky týždenné cookie dáta (bez ohľadu na zadaný interval)
- všetky mesačné cookie dáta (bez ohľadu na zadaný interval)
- celkové cookie dáta (bez ohľadu na zadaný interval)
Day,unix_timestamp_start,unix_timestamp_end,Impresie,Kliky,Videnia,CTR,rCTR,Spotrebovaný kredit,Jednotková cena,Cookies - Impresie,Používatelia - Impressie,Cookies - videnia,Používatelia - videnia ... Week,unix_timestamp_start,unix_timestamp_end,Cookies - Impresie,Používatelia - Impressie,Cookies - videnia,Používatelia - videnia ... Month,unix_timestamp_start,unix_timestamp_end,Cookies - Impresie,Používatelia - Impressie,Cookies - videnia,Používatelia - videnia ... Total,unix_timestamp_start,unix_timestamp_end,Cookies - Impresie,Používatelia - Impressie,Cookies - videnia,Používatelia - videnia

Príklad - štatistika kampane 10069 v období od 1.12.2017 do 31.12.2017 Nech API ID je QWERTyuiopasdfghjklZXCVB Nech API kľúč je MnBvCxyLKJHGfdAs765434qa Nech aktuálny čas je 13.8.2018 11:14:44 (stredoeurópsky letný čas). Potom volanie API funkcie a výsledok môže vyzerať takto: curl https://admin.inres.sk/dataAPI/campaign/?id=QWERTyuiopasdfghjklZXCVB&campId=10069&start=1512082800&end=1514674800&auth=57676c95875e505b2726ac904631d7db50fd3a7d4d0c3765ca63d01a7c44c4f6 Day,1513897200,1513983599,496576,75,130742,0.0151034282768398,0.0574,10.0555433601093,0.134073911468124,95701,59863,44336,30525 Day,1513983600,1514069999,350685,49,82689,0.0139726535209661,0.0593,10.3498657505309,0.211221750010836,100839,63508,39847,27568 Day,1514070000,1514156399,210002,42,57428,0.0199998095256236,0.0731,10.1319543495801,0.241237008323336,61140,37599,26135,17478 Day,1514156400,1514242799,156881,33,45937,0.0210350520458182,0.0718,10.1717891247759,0.308236034084119,49686,31568,22979,15759 Day,1514242800,1514329199,247672,56,73427,0.0226105494363513,0.0763,10.0491253141415,0.179448666323956,72613,46720,34686,24043 Day,1514329200,1514415599,279831,70,84660,0.0250150983986763,0.0827,9.84471919171436,0.1406388455959194,84309,57000,41428,29712 Day,1514415600,1514501999,256790,56,78519,0.0218077027921648,0.0713,9.9947457165125,0.17847760208058036,75091,51053,36458,26355 Day,1514502000,1514588399,178716,44,54583,0.024620067593276503,0.0806,10.1272977882563,0.230165858824007,51923,34840,25437,18065 Day,1514588400,1514674799,162836,43,48067,0.0264069370409492,0.0895,10.0205035970288,0.233034967372763,50592,33257,23840,16789 Day,1514674800,1514761199,276949,57,82180,0.0205814066849853,0.0694,10.4274146662446,0.1829370994078,81458,51337,36418,24734 Week,1513551600,1514156399,228677,135796,98909,65847 Week,1514156400,1514761199,368819,220593,179078,118912 Month,1512082800,1514761199,537854,302487,250730,160026 Total,1510182000,1515365999,939525,492952,451777,273674

Štatistika formátu

URL: https://admin.inres.sk/dataAPI/format/
Parametre:
- id (popis vyššie v časti Autentifikácia)
- auth (popis vyššie v časti Autentifikácia)
- fmtId - celočíselné ID formátu
- start - nepovinný parameter, UNIX čas, celé číslo, musí sa použiť spolu s parametrom end
- end - nepovinný parameter, UNIX čas, celé číslo, musí sa použiť spolu s parametrom start. Ak sú zadané parametre start a end, funkcia vráti dennú štatistiku formátu iba v zadanom časovom intervale, inak funkcia vráti všetky denné dáta formátu.
Výstup: CSV, identický so štatistikou kampane