Dokumentation DFI API. Det danske Filminstitut DFI API. Brugermanual

Transkript

1 Det danske Filminstitut DFI API Brugermanual V

2 Indholdsfortegnelse Indledning... 4 Server... 4 Login... 4 Sprog... 4 Faste søge kriterier... 4 Cached data... 4 Endpoints... 4 Parametre til Film... 6 Parametre til Person... 7 Parametre til Selskab... 7 Parametre til Festival... 7 Parametre til Price... 7 Parametre til InternationalSales... 8 Parametre til SubsidyScheme... 8 Eksempler på kald til DFI API... 8 Datamodel DFIListData Film Person Company FilmCreditItem PersonCreditItem NameItem CompanyProdNameItem PremiereItem ImageItem CollectionItem AccessibilityItem FilmListItem PersonName LanguageItem StamdataItem... 14

3 AdditionalData Film AdditionalData Person AdditionalData Festival Price SubsidyScheme InternationalSales FestivalInformation Address ContactInfo... 16

4 Indledning Dette dokument beskriver brugen af DFI API til søgning i Film databasen. Server Login For at anvende DFI API skal man have udleveret en bruger og et kodeord fra DFI. Bruger og kodeord skal med i Request headeren som Basic HTTP authentication (ikke krypteret base64 encoded). Sprog Default sproget er dansk, men API et understøtter også Engelsk på lister og nogle felter. Skift af sproget angives i Accept-Language parameteren i request headeren, som da-dk, en-us eller en-gb. Faste søge kriterier Søger kun i hovedfilm, personer og selskaber med frigivet dato!=null og max 500 items, medmindre parameteren showall=true er angivet. Cached data Det er muligt at hente data der er cached og derfor kan leveres hurtigere. Data bliver leveret fra en cached datakilde som bliver opdateret 1 gang i døgnet. Hvis man vil undgå cached data kan parameteren "cachedoff=true" tilføjes kaldet. Dette gælder film, person og selskab kald hvor data hentes ud på en ident. f.eks. /v1/film/142?cacheoff=true Se afsnittet med eksempler. Endpoints Oversigt over alle endpoint i DFI API Version=v1 Alle endpoint skal have version først, som f.eks.../v1/film/47. Film /film/[id][?cacheoff=true] /film?[ parametre] /film/additionaldata/[id][?cacheoff=true] Person /person/[id] [?cacheoff=true] /person?name=[name]&function=[func1,func2] /person/credits Henter data til film ud fra filmens ident Lister alle film der matcher parametre. Se liste parameter til film Henter Website, Støtteinformation, festivaler og priser Henter data til person ud fra personens id Lister selskaber der matcher parameter Se liste parameter til person Lister alle credit typer der kan søges på

5 /person/additionaldata/[id] [?cacheoff=true] Selskab /company/[id][?cacheoff=true] /company/name=[name]&type=[type] /company/types /company/productioncompany/types /company/additionaldata/[id] [?cacheoff=true] Festival /festival/[id] /festival/name=[name]&year=[type] Priser /price/[id] /price/name=[name] (den gamle functions) Henter priser for film som personen har deltaget i Henter selskab ud fra id Lister selskaber der matcher parameter Se liste parameter til selskab Lister alle selskabstyper Lister alle produktionselskabstyper Henter priser for film som personen har deltaget i. Henter festival ud fra id Lister festivaler der matcher parameter Se liste parameter til festival Henter prise ud fra id Lister priser der matcher parameter Se liste parameter til festival Internationale salgsagenter / internationalsales/[id] Henter salgsagenter ud fra id / internationalsales/name=[name] Lister salgsagenter der matcher parameter Se liste parameter til international sales Støtteordninger / subsidyscheme/[id] Henter støtteordning ud fra id / subsidyscheme/name=[name] Lister støtteordninger der matcher parameter Se liste parameter til subsidyscheme Stamdata film/categories film/subcategories /film/censorcodes /film/countries /person/credits /company/types /company/productiontypes Liste af stamdataitem (DK,EN) Liste af stamdataitem (DK,EN) Liste af stamdataitem (DK,EN) Liste af stamdataitem (DK,EN) Liste af stamdataitem (DK,EN) Liste af stamdataitem (DK,EN) Liste af stamdataitem (DK,EN)

6 Parametre til Film Navn Title ReleaseStart ReleaseEnd ProductionCountry HasClip HasTrailer IsInFilmstriben IsInVideotek CensorCode Category SubCategory AdditionalIds Price SubsidyScheme Sales Festival onlymainfilm sortby ShowAll Skip Take PremiereStart PremiereEnd HasAssessmentText Bemærkning Søge i alle titel felter. Originaltitel, dansktitel, alttitler og supplerende titler % søger som like _ enkelt karakter Årstal Årstal dk eller dk,gb kommasepareret ved flere Har film i samlingen Har trailer i samling Kan kun søges =true. Henter film der kan ses på filmstriben eller filmcentralen Kan kun søges =true. Henter film der kan ses på Cinematekts bibliotek Eks. To15,fr.u7 Slå op med kategorikode Slå op med underkategorikode kommasep Identer til Additional data Additionaldata ident price Additionaldata ident SubsidyScheme Additionaldata ident sales Additionaldata ident Festival Default = true - Henter kun hovedfilm false henter alt trailer m.m Enten releaseyear, title eller assessmentreleasedate Default=false returnerer max 500 items true = alt returneres Spring [skip] antal over Returnere kun [take] antal YYYY-MM-DD (film der har premiere efter dato) YYYY-MM-DD (film der har premiere før dato) Kan kun søges =true. Henter film der har fået en vurdering af medierådet

7 Parametre til Person Navn Bemærkning Name Navn på person. Der søges på lastname firstname, hvis der ikke indgår et wildcard. Firstname Lastname Credit Skip Take Wildcard % søger som like _ enkelt karakter Hvis firstname eller lastname parameter er udfyldt, så ignoreres Name parameteren Søg på fornavn Søg på efternavn Credit (CrediytType) på film i en kommasepareret liste Spring [skip] over Returnere kun [Take] antal Parametre til Selskab Navn Bemærkning Name Navn på selskab. Der søges på navn. Wildcard % søger som like _ enkelt karakter Type Skip Take Selskab type Spring [skip] over Returnere kun [Take] antal Parametre til Festival Navn Bemærkning Name Navn på festival. Der søges på navne der indeholder strengen Year Årstallet festivalen blev afholdt Skip Spring [skip] over Take Returnere kun [Take] antal SortBy Sorter efter Name eller Year Parametre til Price Navn Bemærkning Name Navn på Prisen. Der søges på navne der indeholder strengen Skip Spring [skip] over Take Returnere kun [Take] antal

8 Parametre til InternationalSales Navn Bemærkning Name Navn på salgsagenten. Der søges på navne der indeholder strengen Skip Spring [skip] over Take Returnere kun [Take] antal Parametre til SubsidyScheme Navn Bemærkning Name Navn på støtteordningen. Der søges på navne der indeholder strengen Skip Spring [skip] over Take Returnere kun [Take] antal Eksempler på kald til DFI API Endpoint eksempler på Web server Film Hent film med id = Hent liste af film med en titel der starter med jagten og er udkommet mellem 2000 og 2008 inkl., sorter på titel. Hent liste af film der er i videoteket og er udkommet i 2010 og derefter Hent de 30 første film der er udgivet i 2017 og sorter by dato Hent yderligere data (festival og priser og salgsoplysninger) Person Hent person med ID = 47 List personer hvis efternavn starter med abil og er instruktør List personer der har jytte til fornavn List personer med fornavn Lars Von von

9 List personer der har ordet søren i fornavn eller efternavn List personer hvis efternavn starter med søren og er krediteret som instruktør eller manuskript forfatter Liste af 30 personer, men spring de første 10 over Selskab Hent selskab med id = 16 List alle selskaber med typen produktion List alle selskaber hvis navn starter med zent og har typen distribution selskab Stamdata Hent alle credits Hent alle selskabstyper Hent alle censurkoder Hent alle lande

10 Datamodel Beskrivelse af de entiteter der er implementeret i DFI Open API. DFIListData Felt Beskrivelse Type ResultCount Hvor mange rækker returneres der number TotalResultCount Hvor mange rækker giver søgningen i alt number FilmList[] Liste af FilmListItem PersonList[] Liste af PersonName SelskabList[] Liste af CompanyListItem Film Id Title Hvis dansk vises den ellers original String DanishTitle Dansk titel String OriginalTitle Original titel String AltTitle Viser alle titler der ikke er udenlandske Liste af s ForeignTitles Viser udenlandske titler List af ForeignTitles{Language,Title} LengthInMin number LengthInMeters number ReleaseYear number Description Synopsis String Literature Bøger, website, andre materialer String Category Premiere Viser biograf premiere (bp) PremiereItem ProductionYear number ProductionCountries Liste af s ProductionCompanies Liste af CompanyProdNameItem DistributionCompanies Liste af NameItem Requestors Liste af NameItem Width FilmFormat ColorSystem ToneSystem Classification Medierådets vurdering AssessmentText Medierådets begrundelse SubCategories Liste af s PersonCredits Liste af PersonCreditItem Comment String Idea Genre Liste af stings FilmstribeId Findes filmen på filmstriben eller Liste af stings filmcentralen DKFilm Findes filmen på Danmarkpaafilm.dk Boolean InVideoteket Kan filmen ses på Cinematekets videotek Boolean

11 Accessibillity Objekt bestående af bool Subtitles, bool AccessibillityItem AudioDescription Keywords Emneord Liste af s Collections Samlinger Liste af CollectionItem DialogLanguage Filmens dialogsprog Liste af s ImageUrl Depricated Images Billeder Liste af ImageItem Posters Plakater Liste af ImageItem Programs Programmer Liste af ImageItem Videos Streaming Liste af ImageItem HasPoster Har plakater Boolean HasStills Har stillbilleder Boolean HasVideo Har video (streaming) Boolean HasManus Har manuskript, der kan læses i Boolean Cinematekets bibliotek HasAdditionalData Kan der findes mere data på Boolean /film/additionaldata/[id] Type String Media Liste af udklip fra fx pressen der kan findes på Cinematekets Bibliotek Liste af Media items Person Id Personenes Id number Name Personens Navn FirstName Fornavn LastName Efternavn Description Teksten tilknyttet personen YearOfBirth Årstallet personen er født number YearOfDeath Årstallet personen er død number FilmCredits Alle de film personen har medvirket i Liste af FilmCreditItem OtherNameIds Hvis personen har skiftet navn Liste af id er ImageUrl Depricated Images Billeder Liste af ImageItems HasAdditionalData Boolean Company Id Selskabs id number Name Selskabets navn Description kommentar Productions Liste af selskabets produktioner FilmListItemDTO Distribution FilmListItemDTO Requestor FilmListItemDTO Images Billeder Liste af ImageItems

12 FilmCreditItem Type Type tilknyttelse til film TypeCode Type id sting Description Specificering af type Id Film ident number Title Film titel ReleaseYear Film udsendelsesår number Category PersonCreditItem Id Person ident number Name Fornavn Efternavn FirstName LastName Type Type tilknyttelse til film TypeCode Typens Id Description Specificering af type Sorting Sortering int NameItem Id Person ident number Name Fornavn Efternavn CompanyProdNameItem Id Person ident number Name navn Type Type tilknyttelse til film (kan være null) TypeId Types id (kan være null) int Comment Kommentar (kan indeholde finansierings oplysninger) PremiereItem PremiereType PremiereDate Filmens premieredato DateTime PremiereTheatres Liste af biographer/medier PremiereComment Kommentar om premieren String

13 ImageItem Caption Categori Credit PathMicr url til lille billede PathMini url til mellem billede DownloadUrl url til billede i fuldstørrelse AssetsType Billede type ImageHeight ImageWidth FileType Urgency Nummer der prioriterer billede: 2 hovedbillede, 3 press, 5 default CollectionItem Type fprogram Path Sti til filen FileName Filnavn Description Evt. beskrivelse AccessibilityItem Subtitle Undertekster boolean AudioDescription Synstolkning boolean FilmListItem Id filmid number Title ReleaseYear number Category PersonName Id filmid number Name Fornavn Efternavn FirstName LastName LanguageItem Language Language code

14 Text StamdataItem Code Kode Name Tilhørende navn

15 AdditionalData Film AdditionalData Id number FidaId The Id used for the API number Title String TitleDA Dansk title TitleEN Engelsk title DFISubsidyScheme SubsidyScheme SubsidyScheme InternationalSales InternationalSales objekt InternationalSales FestivalInformation Objekt Festivals Liste af festivaler filmen har deltage på List af Festival Prices Liste af priser filmen har modtaget (samt tilhørende festival) List af Price Person AdditionalData Id number Festivals Liste af festivaler filmen har deltage på List af Festival Prices Liste af priser filmen har modtaget (samt List af Price tilhørende festival) IsInDFIBook Kan personen finds på DFIBogen.dk Bool Festival Id Festival-id number Title Festivalens navn Year Festivalens Årstal number StartDate Festivalens startdato DateTime EndDate Festivalens slutdato DateTime EventName Yderligere navn Price Id Pris id number Name Prisens navn SubsidyScheme Id Støtteordningens id number Scheme Støtteordningens navn Specifikation Specifikation Type Type

16 Premis Vilkår Date Bevillingsdato DateTime InternationalSales Id Salgsagentens id number Name Salgsagentens navn Address Salgsagentens adresse Object ContactInfo Kontakt informationer, mail, telefon Object FestivalInformation Id Firmaets id number Name Firmaets navn Address Firmaets adresse Object ContactInfo Kontakt informationer, mail, telefon Object Address Street Gadenavn number House Husnummer Zip Postnummer String City By String Country Land String PostBox Postboks String Additional1 Ekstra info String Additional2 Ekstra info String ContactInfo Phone String CellPhone String Fax String String Website String