Filmtipset API

Information
Filmtipset.se:s API är till för att andra webb-sidor eller applikationer ska kunna använda filmtipsets information för att integrera med sina egna applikationer eller webb-sidor.

API:t bygger på att http-requests görs till ett särskillt script på filmtipset.se med ett antal parametrar eller med en XML. Resultatet returneras sedan I form av XML eller JSON.

Säkerhet
För att garantera att ingen missbrukar filmtipsets API så krävs en speciell nyckel från filmtipset för att kunna få ut information ur API:t. Nyckeln genereras av filmtipset.se, kontakta oss för att få din nyckel. Viss funktionalitet kräver också en speciell besökarnyckel som filmtipsets användare kan generera på filmtipset och sedan tillhandahålla till api- användarens applikation. Funktionalitet som kräver detta är t.ex. att sätta betyg på filmer.

Funktionalitet
Grunden till API-användningen är att requests görs och att man antingen skickar in en XML eller ett antal parametrar. Om man skickar in parametrar görs det enligt följande mall:
http://www.filmtipset.se/api/api.cgi?accesskey=&u serkey=&usernr=&returntype=&callback=my_callback_functi on&action=&annan_parameter=annat värde

där:
  • accesskey är nyckeln som specificeras ovan.
  • userkey är den användar-nyckel som specas ovan.
  • usernr är ett användar-nummer som kan användas för att hämta
  • mindre känslig information
  • action är den informationstyp man vill ha ut (filminfo, sökning etc.), se spec nedan för mer detaljer.
  • returntype beskriver på vilket sätt man vill ha tillbaka resultatet
  • callback används om man vill när man tar emot resultatet som JSON
Om man anger ett callback-funktionsnamn här så får man tillbaka JSON-resultatet som ett funktionsanrop till den angivna funktionen med resultatet som parameter. För XML har denna parameter ingen effekt.

Andra parametrar är beroende på vilken informationstyp man vill ha. Även xml-requesten skickas till http://www.filmtipset.se/api/api.cgi. Content-type ska då vara text/xml och själva xml:en skickas som content / body i requesten.


Informationstyper

  • movie: Hämta information om en given film. Parameter som ska skickas in är “id” och värdet på den ska vara en kommaseparerad lista över de filmer man vill ha information om. Skickar man med ett user-nr eller user-key får man även betyg (beräknat eller satt) för den användaren.
  • person: Hämtar information om en given skådespelare/regissör/manusförfattare. Parametern som ska skickas in är “id” och värdet på den ska vara en kommaseparerad lista över de personer filmer man vill ha information om. Skickar man med ett user- nr eller user-key får man även betyg (beräknat eller satt) för den användaren.
  • comment: Kommentera en film. Skicka in film-id:t som parametern “id” och kommentaren som parametern “comment”. Kräver användarnyckel. Det som returneras är film-infon (samma som om man gör en movie-request).
  • Imdb: Hämtar samma information som “movie”, men baserat på ett IMDb-nummer kopplat till en film på filmtipset. Observera att man ska skippa “tt” i början av IMDb-numret, men ta med eventuella inledande 0:or.
  • list: Hämta en lista av filmer. Parameter som ska skickas in är “id” och specificera vilken av lista som ska hämtas . Det kan antingen vara “bio”, “video”, “tv”, “owned”, ”wantedlist”, “seen” eller ett paket-nummer (paketet kan göras på filmtipset.se). Owned ger en lista över de filmer som en användare äger, wantedlist över de filmer en användare vill se och seen en lista över de filmer en användare sett. Det som returneras är en lista med film-id, titel, url och betyg. Information om dessa kan sedan hämtas ut via ett nytt anrop. Man kan även hämta ut Cinematekets lista genom att ange “Cinemateket”, “Cinemateket Malmö” eller “Cinemateket GBG” som lista.
  • add-to-list: Lägg till en film till en lista. Kräver en userkey för användaren man ska lägga till för. Paramtern för vilken lista är “id” och kan vara “owned”, “wantedlist” eller ett paket-nummer som ägs av den användaren. Parametern “movie” anger vilken film som ska läggas till listan. Det som returneras är samma som för kommandot list.
  • user: Används för att hämta ut information om en användare. Tar parametern id som är vilken användare som ska hämtas information om. Om man även skickar in parametern “ignorelists=1” så returnerar den INTE de personliga listor som en användare har gjort, och därmed kan man spara tid i anropet.
  • user-latest: Om man vill ha en lite fylligare lista över en användares senaste betygsatta (med titel, betyget de satte osv.) så kan man anropa denna funktion med medlemmen man är intresserad av som parametern id.
  • recommendations: Hämta ut filmtips. Se Appendix B för vilka ID:n som är giltiga.
  • user-messages: Används för att hämta ut en lista på de 100 senaste meddelandena för en användare (texten är de första 300 tecknen). Måste ha en userkey (och man kan bara hämta för den användaren vars nyckel man anger). Om man anger ett id med ett mappnamn så kommer man få meddelanden i den mappen i stället. Ett “magisk” mapp heter “unread” och ger olästa meddelanden i inkorgen.
  • message: Se ett helt meddelande. Parametern “id” är det meddelande-id som finns i meddelandelistan man får med “user- message”.
  • mark-message-unread: Markerar ett meddelande som oläst. Parametern “id” är det meddelande-id som finns i meddelandelistan man får med “user-message”.
  • send-message: Skicka meddelande till en annan medlem. Parametrar som ska skickas in är “recipient” (id på medlem som ska ta emot meddelandet), “reply” (id på det meddelande som det man skriver är svar på – inte nödvändigt vid nytt meddelande), ”subject” (meddelandets ämne), “body” (meddelandets innehåll). Kräver användarnyckel.
  • grade: Används för att sätta ett betyg åt en användare. Kräver user- key. Parametrar som ska användas är “id” som är ett film-id och “grade” som är ett betyg i skalan 1-5.
  • search: Tar parametern id som har värdet av det man vill söka på. Returnerar en lista med filmer samt info om dem.
Mer info:
För mer info och en användar-nyckel, kontakta Filmtipset. http://nyheter24.se/filmtipset/tailpages.cgi?page=Kontakt

Inga kommentarer:

Skicka en kommentar