Events API

Events API används för att få tillgång till våra evenemang: ladda ner texter, bilder, länkar med mera och smidigt kunna publicera de på andra platser på webben.

Du behöver en API-nyckel

För att komma igång behöver du en API-nyckel från oss. Skicka ett mejl till info@kulturbiljetter.se eller ring oss på 08 - 50 25 40 80 (klicka här för att se öppettider).

Teknisk dokumentation

Events API är ett RESTful API. Läs mer om REST här (Wikipedia).

Grundläggande saker

  • Alla svar skickas som JSON
  • All kommunikation med APIet måste ske över HTTPS
  • Lämpliga felkoder returneras, exempelvis "400 Bad Request" om anropet inte är giltigt (exempelvis på grund av fel syntax). I de flesta fall returneras också ett felmeddelande.
  • Versionen specificeras i URLen, exempelvis "v1"
  • Senaste version: version 1

Autentisering

För att autentisera dig med din API-nyckel så skickar du följande header med varje anrop till APIet

Authorization: Token {API-nyckel}

Cache och ETags

Vi använder ETags som valideringsmekanism för caching av evenemang.

Det går ut på att du sparar varje ETag ihop med respektive evenemangs id-nummer. Vid anropet för att hämta detaljer om ett evenemang så skickar du din sparade ETag till vår server (se hur nedan). Vid anropet för att hämta en lista på evenemang så ingår alla ETags och du kan då jämföra dina sparade med de i listan och utifrån det bestämma vilka evenemang som behöver hämtas.

Om vi har samma ETag så har ingenting ändrats i evenemanget, om det inte är samma ETag så har någonting ändrats och alla detaljer behöver hämtas på nytt.

För att skicka din sparade ETag till vår server så skickar du följande header

If-None-Match: "{ETag}"

Om du skickar en ETag på det här sättet och den överensstämmer med senaste ETag så svarar servern med "304 Not Modified".

När servern skickar senaste ETag så används följande header

Exempel på ETag från vår server

ETag: "4628e98dc9bda56b69403ab1986158c0"

Anrop för att hämta lista på evenemang

För att hämta en lista på evenemang använder du GET-anropet

https://kulturbiljetter.se/api/v1/events/

Exempel på svar

{
    "0": {
        "event_id": "1291",
        "ETag": "4628e98dc9bda56b69403ab1986158c0"
    },
    "1": {
        "event_id": "1293",
        "ETag": "cf8708058a437bf89bea4487c29bd088"
    },
    "2": {
        "event_id": "1294",
        "ETag": "f6214307a0111d67370bc0841dd6c355"
    }
}

Parametrar i svaret

event_id Evenemangets id-nummer
ETag Evenemangets nuvarande ETag. Använd denna för att veta om något ändrats i evenemanget sedan senaste anropet, se ovan om cache

Anrop för att hämta detaljer om ett evenemang

För att hämta detaljer om ett evenemang använder du ett GET-anrop enligt mallen

https://kulturbiljetter.se/api/v1/events/{event_id}

Exempel på svar

{
    "title": "Lorem ipsum",
    "presentation_short": "<p>Lorem ipsum &amp; dolor sit amet</p>",
    "presentation_long": "<p>Lorem ipsum dolor <strong>sit amet</strong>, consectetur adipiscing elit.</p>",
    "unixtime_release": "1410478792",
    "organizer": {
        "organizer_id": "1023",
        "name": "Hattbaren",
        "logo": "https://kulturbiljetter.se/files/logos/1023/c95efdd0.jpg"
    },
    "images": {
        "0": "https://kulturbiljetter.se/files/evenemang/1291/473c1e7e.png"
    },
    "trailers": {
        "0": "http://www.youtube.com/embed/eV5Qaaa000A?rel=0"
    },
    "dates": {
        "0": {
            "date_id": "1021",
            "location_id": "1191",
            "unixtime_open": "1412208093",
            "unixtime_start": "1412208147",
            "date_only": false,
            "url_checkout": "https://kulturbiljetter.se/varukorg/1291/1021/lorem-ipsum/"
        },
        "1": {
            "date_id": "1022",
            "location_id": "1191",
            "unixtime_open": "1412294512",
            "unixtime_start": "1412294581",
            "date_only": false,
            "url_checkout": "https://kulturbiljetter.se/varukorg/1291/1022/lorem-ipsum/"
        }
    },
    "locations": {
        "0": {
            "location_id": "1191",
            "name": "Hattbaren",
            "street": "Hattbarsgatan 88",
            "vicinity": "Sollerön",
            "city": "Mora"
        }
    },
    "url_checkout": "https://kulturbiljetter.se/varukorg/1291/lorem-ipsum/",
    "url_event_page": "https://kulturbiljetter.se/evenemang/1291/lorem-ipsum/",
    "url_organizer_serp": "https://kulturbiljetter.se/arrangör/1023/hattbaren/"
}

Parametrar i svaret

title Evenemangets titel
presentation_short Kortfattad presentation av evenemanget. Detta är HTML för rich text-formatering med icke-formateringstaggar och specialtecken utbytta mot HTML entities
presentation_long Presentation av evenemanget. Detta är HTML, se mer vid presentation_short ovan
unixtime_release Tid för biljettsläpp. UNIX timestamp
organizer Detaljer om arrangören
organizer_id Arrangörens id-nummer
name Arrangörens namn
logo URL till arrangörens logga. Kan vara NULL
images Innehåller URLs till bilder. Obegränsat antal. Kan vara NULL
trailers Innehåller URLs till trailers (redo för att bli embedded). Obegränsat antal. Kan vara NULL
dates Detaljer om föreställningar. Obegränsat antal
date_id Föreställningens id-nummer
location_id Id-nummer till föreställningens spelplats
unixtime_open Tid när arrangörens kassa öppnar. UNIX timestamp
unixtime_start Tid när föreställningen börjar. UNIX timestamp
date_only True om tidpunkten för föreställningen ska presenteras med endast datum och inte klockslag, annars false
url_checkout URL till Kulturbiljetters kassa med evenemanget och föreställningen förvalda
locations Detaljer om spelplatser. Obegränsat antal
location_id Spelplatsens id-nummer
name Spelplatsens namn. Kan vara NULL
street Spelplatsens gatuadress. Kan vara NULL
vicinity Stadsdel / område som spelplatsen är i. Kan vara NULL
city Stad som spelplatsen är i. Kan vara NULL
url_checkout URL till Kulturbiljetters biljettkassa med evenemanget förvalt
url_event_page URL till evenemangets sida hos Kulturbiljetter
url_organizer_serp URL till ett sökresultat hos Kulturbiljetter med arrangörens samtliga evenemang ("arrlänk")
Synpunkter?