Virksomme ord API — Dokumentasjon

Virk­somme Ord er en data­base over norske poli­tiske taler. Tal­ene er pre­sen­tert på hjemmes­i­den virksommeord.uib.no, men det går også an å nå tal­ene via et API. Dette API-et returner­er XML-fil­er som er let­tere for data­mask­in­er å behan­dle enn html.

URL-struktur og koding

OBS! API-et har fått ny url!

Grunn-URLen for API-et er http://aurora.uib.no/vo/api/1/

Videre må man spe­si­fis­ere en funksjon og med­føl­gende para­me­tre på denne for­men: <funksjon>?<parametre>. Der­som en funksjon tar flere para­me­tre skilles disse ved hjelp av “&”. For funksjo­nen Tale­In­fo blir dermed hele URLen http://aurora.uib.no/vo/api/1/TaleInfo?id=2 der Tale­In­fo er funksjo­nen og id=2 er para­me­tr­eret til funksjo­nen. Legg merke til at funksjon og para­me­ter skilles med ?.

Alle XML-filene API­et returner­er er kodet med UTF‑8, men alle søkestrenger som sendes til API-et må kodes med  ISO-8859–1. Hvis ikke vil API-et returnere en feil.

Ved feil, i dette til­fel­let at en id som er angitt som para­me­ter ikke finnes, vil API-et returnere føl­gende XML-struktur:

<?xml version="1.0" encoding="UTF-8" ?> 
 <Exception> 
 <Message>Ugyldig id</Message> 
 </Exception>

Oversikt over funksjoner

De tilgjen­gelige funksjo­nen kan deles opp i tre kat­e­gori­er: Lis­te­funksjon­er, info­funksjon­er og søkefunksjoner

Listefunksjoner

Lis­te­funksjonene returner­er sorterte lis­ter av alle de aktuelle ele­mentene i data­basen. Funksjonene tar ingen parametre.

ListeTaler

Returner­er en kro­nol­o­gisk liste av alle taler i data­basen. Den eld­ste tal­en kom­mer først.

http://aurora.uib.no/vo/api/1/ListeTaler

XML-struk­tur:

<?xml version="1.0" encoding="UTF-8" ?> 
 <Speech-list length="1"> // rotelement, (1 tale). 
 <Speech id="148"> // representerer en tale i databasen. 
 <Title>Hagens Levende Ord tale</Title> // tittel på tale. 
 <Location>Bergen</Location> // stedet talen ble holdt på. 
 <Event>Sommerfestival</Event> // anledningen til talen. 
 <Date> // dato til talen. 
 <Day /> // dagen i måneden (1-31) talen ble holdt på. Her er dette elementet tom, dvs dagen er ukjent. 
 <Month>7</Month> // måneden talen ble holdt på (1-12). 
 <Year>1990</Year> // året talet ble holdt. 
 </Date> 
 <Person id="103"> // taleholderen. 
 <Name> // navn på taleholder. 
 <First>Carl Ivar</First> // fornavn. 
 <Last>Hagen</Last> // etternavn. 
 </Name> 
 </Person> 
 </Speech> 
 </Speech-list>

ListePersoner

Returner­er en liste over alle per­son­er i data­basen, sortert alfa­betisk på etter­navn, så på fornavn.

http://aurora.uib.no/vo/api/1/ListePersoner

XML-struk­tur:

<?xml version="1.0" encoding="UTF-8" ?> 
 <Person-list length="1"> // rotelementet, (1 person). 
 <Person id="103"> // representerer en person i databasen. 
 <Name> // navnet til personen. 
 <First>Carl Ivar</First> // fornavn. 
 <Last>Hagen</Last> // etternavn. 
 </Name> 
 <Born>1945</Born> // fødselsår. 
 <Dead /> // dødsår. 
 <Speeches>5</Speeches> // antall taler denne personen har holdt (som er registrert i databasen). 
 </Person> 
 </Person-list>

ListePartier

Returner­er en liste over alle parti­er i data­basen, sortert alfabetisk.

http://aurora.uib.no/vo/api/1/ListePartier

XML-struk­tur:

<?xml version="1.0" encoding="UTF-8" ?> 
 <Party-list length="1"> // rotelement, (1 parti/organisasjon). 
 <Party id="41"> // representerer et parti/organisasjon. 
 <Name>FRP</Name> // navnet til partiet/organisasjonen. 
 <Members>1</Members> // antall personer i databasen som er tilknyttet til dette partiet/organisasjonen. 
 </Party> 
 </Party-list>

Parti­er bruk­ers til å rep­re­sen­tere parti­er (FRP) eller organ­isas­jon­er (LO).

ListeEmner

Returner­er en liste over alle emn­er i data­basen, sortert alfabetisk.

http://aurora.uib.no/vo/api/1/ListeEmner

<?xml version="1.0" encoding="UTF-8" ?> 
 <Keyword-list length="3"> // rotelementet, (3 emner). 
 <Keyword id="82"> // representerer et emne i databasen. 
 <Name>Islam</Name> // navnet på emnet. 
 <Speeches>5</Speeches> // antall taler på dette emnet. 
 </Keyword> 
 <Keyword id="83"> 
 <Name>Israel</Name> 
 <Speeches>1</Speeches> 
 </Keyword> 
 <Keyword id="102"> 
 <Name>Religion</Name> 
 <Speeches>0</Speeches> // hvis ingen taler på gitt emne skrives tallet null (som her). 
 </Keyword> 
 </Keyword-list>

ListeSjangre

Returner­er en liste over sjan­gre i data­basen, sortert alfabetisk.

http://aurora.uib.no/vo/api/1/ListeSjangre

XML-struk­tur:

<?xml version="1.0" encoding="UTF-8" ?> 
 <Genre-list length="1"> // rotelementet, (1 sjanger). 
 <Genre id="41"> // representerer en sjanger i databasen. 
 <Name>Debatt</Name> // navn på sjanger. 
 <Speeches>5</Speeches> // antall taler på denne sjangeren. 
 </Genre> 
 </Genre-list>

Infofunksjoner

Info­funksjonene returner­er infor­masjon om en spe­si­fikk oppføring i data­basen. Funksjonene krev­er ett para­me­ter, id, som angir en oppføring.

TaleInfo

Returner­er infor­masjon om en gitt tale, samt:

• alle emn­er til tal­en (alfa­betisk).
• alle sjan­gre til tal­en (alfa­betisk).
• alle bilder til tale.
• alle lyd­fil­er til talen.
• alle video­er til talen.

http://aurora.uib.no/vo/api/1/TaleInfo?id=105

XML-struk­tur:

<?xml version="1.0" encoding="UTF-8" ?> 
 <Speech id="148"> // rotelement, representerer en tale. 
 <Title>Hagens Levende Ord tale</Title> // tittel på talen. 
 <Location>Bergen</Location> // stedet talen ble holdt. 
 <Event>Sommerfestival</Event> // Anledningen til talen. 
 <Date> // dato talen ble holdt på. 
 <Day /> // dag i måneden (1-31). 
 <Month>7</Month> // måned (1-12). 
 <Year>1990</Year> // år. 
 </Date> 
 <Person id="103"> // taleholder. 
 <Name> // navn på taleholder. 
 <First>Carl Ivar</First> // fornavn. 
 <Last>Hagen</Last> // etternavn. 
 </Name> 
 </Person> 
 <Source>Lydfil</Source> // klidehenvisning for talen. 
 <Reference>Levende Ord</Reference> // videre referanser. 
 <Introduction>Intro til talen.</Introduction> // introduksjon til talen. Her kan det være mye tekst (ren tekst). 
 <Keyword-list length="3"> // alle emner til talen (alfabetisk), (3 emner). 
 <Keyword id="82">Islam</Keyword> // representerer et emne (navn på emnet). 
 <Keyword id="83">Israel</Keyword> 
 <Keyword id="102">Religion</Keyword> 
 </Keyword-list> 
 <Genre-list length="1"> // alle sjangre til talen (alfabetisk), (1 sjanger). 
 <Genre id="41">Debatt</Genre> // representerer en sjanger (navn på sjanger). 
 </Genre-list> 
 <Image-list length="2"> // alle bilder til talen, (2 bilder). 
 <Image id="162"> // representerer et bilde i databasen. 
 <URL>http://lotus.uib.no:8008/retorikk/bilde/bilde162.jpeg</URL> // URL til bildet. 
 <Format /> // formatet til bildet, f. eks. JPEG. NB: dette elementet er ofte tomt (som her). 
 <Annotation>Bilde av Hagen</Annotation> // bildetekst. 
 <Main>true</Main> // om dette bildet er et hovedobjekt, se 'PersonInfo'. 
 </Image> 
 <Image id="163"> 
 <URL>http://lotus.uib.no:8008/retorikk/bilde/bilde163.jpg</URL> 
 <Format /> 
 <Annotation>Bilde av Hagen</Annotation> 
 <Main>false</Main> 
 </Image> 
 </Image-list> 
 <Audio-list length="1"> // antall lyd(fil)er til talen, (1 lyd). 
 <Audio id="42"> // representerer en lyd i databasen. 
 <URL>http://lotus.uib.no:8008/retorikk/lyd/lyd42.mp3</URL> // URL til lyden. 
 <Format>MP3</Format> // format på lyden. NB: dette elementet er ofte tomt. 
 <Annotation>Hagens tale.</Annotation> // forklaring til lyden. 
 <Main>true</Main> // om denne lyden er et hovedobjekt. 
 </Audio> 
 </Audio-list> 
 <Video-list length="1"> // alle videoer til denne talen, (1 video). 
 <Video id="1"> // representerer en video i databasen. 
 <URL>http://lotus.uib.no:8008/retorikk/video/video1.avi</URL> // URL til video. 
 <Format>AVI</Format> // format på videoen. NB: dette elementet er ofte tomt. 
 <Annotation>Hagens tale.</Annotation> // forklaring til videoen. 
 <Main>true</Main> // om denne videoen er et hovedobjekt. 
 </Video> 
 </Video-list> 
 <Language>Norsk</Language> // språket talen er holdt på. 
 <Document id="156"><HTML><BODY> <p>es New Rom</HTML>...</Document> // selve talen i HTML-fomat. 
 </Speech>

PersonInfo

Returner­er infor­masjon om en gitt per­son, samt:

• alle taler som denne per­so­n­en har holdt (kro­nol­o­gisk).
• alle parti­er denne per­so­n­en er tilknyt­tet (alfa­betisk).
• alle bilder av personen.

http://aurora.uib.no/vo/api/1/PersonInfo?id=61

XML-struk­tur

<?xml version="1.0" encoding="UTF-8" ?> 
 <Person id="103"> // rotelement, representerer en person. 
 <Name> // navn på person. 
 <First>Carl Ivar</First> // fornavn. 
 <Last>Hagen</Last> // etternavn. 
 </Name> 
 <Born>1945</Born> // fødselsår. 
 <Dead /> // dødsår. 
 <Info>Info om Hagen.</Info> // informasjon om personen. 
 <Party-list length="1"> // liste med partier (alfabetisk) denne personen er tilknyttet til, (1 parti). 
 <Party id="41"> 
 <Name>FRP</Name> 
 </Party> 
 </Party-list> 
 <Speech-list length="1"> // liste med taler (kronologisk) denne personen har holdt, (1 tale). 
 <Speech id="148"> 
 <Title>Hagens Levende Ord tale</Title> 
 <Location>Bergen</Location> 
 <Event>Sommerfestival</Event> 
 <Date> 
 <Day /> 
 <Month>7</Month> 
 <Year>1990</Year> 
 </Date> 
 </Speech> 
 </Speech-list> 
 <Image-list length="2"> // bilder av denne personen, (2 bilder). 
 <Image id="141"> // representerer et bilde i databasen. 
 <URL>http://bulmeurt.uib.no:8080/retorikk/media/bilde/bilde141.jpg</URL> // URL til bildet. 
 <Format /> // format til bildet f. eks. JPEG. NB: dette elementet er ofte tomt (som her). 
 <Annotation>bilde av Hgen</Annotation> // Bildetekst. 
 <Main>false</Main> // Alltid true eller false, avhengig av om dette bildet er et hovedobjekt. 
 </Image> 
 <Image id="134"> 
 <URL>http://bulmeurt.uib.no:8080/retorikk/media/bilde/bilde134.jpg</URL> 
 <Format /> 
 <Annotation>bilde av Hagen</Annotation> 
 <Main>true</Main> 
 </Image> 
 </Image-list> 
 </Person>

PartiInfo

Returner­er infor­masjon om et gitt parti/organisasjon (PO), samt alle per­son­er som er tilknyt­tet dette PO.

http://aurora.uib.no/vo/api/1/PartiInfo?id=41

XML-struk­tur:

<?xml version="1.0" encoding="UTF-8" ?> 
 <Party id="41"> // rotelementet, representerer et PO i databasen. 
 <Name>FRP</Name> // navn på PO. 
 <Info>Info om FRP.</Info> // info og historikk om PO. 
 <Person-list length="1"> // liste med personer (alfabetisk, etternavn og fornavn) som er tilknyttet dette PO, (1 person). 
 <Person id="103"> 
 <Name> 
 <First>Carl Ivar</First> 
 <Last>Hagen</Last> 
 </Name> 
 <Born>1945</Born> 
 <Dead /> 
 <Speeches>5</Speeches> 
 </Person> 
 </Person-list> 
 </Party>

EmneInfo

Returner­er infor­masjon om et gitt emne, samt alle taler på dette emnet.

http://aurora.uib.no/vo/api/1/EmneInfo?id=102

XML-struk­tur:

<?xml version="1.0" encoding="UTF-8" ?> 
 <Keyword id="102"> // rotelement, representerer et emne i databasen. 
 <Name>Religion</Name> // navn på emnet. 
 <Speech-list length="1"> // liste med taler (kronologisk) på dette emnet, (1 tale). 
 <Speech id="148"> 
 <Title>Hagens Levende Ord tale</Title> 
 <Location>Bergen</Location> 
 <Event>Sommerfestival</Event> 
 <Date> 
 <Day /> 
 <Month>7</Month> 
 <Year>1990</Year> 
 </Date> 
 <Person id="103"> 
 <Name> 
 <First>Carl Ivar</First> 
 <Last>Hagen</Last> 
 </Name> 
 </Person> 
 </Speech> 
 </Speech-list> 
 </Keyword>

SjangerInfo

Returner­er infor­masjon om en gitt sjanger, samt alle taler på denne sjangeren.

http://aurora.uib.no/vo/api/1/SjangerInfo?id=1

XML-struk­tur

<?xml version="1.0" encoding="UTF-8" ?> 
 <Genre id="1"> // rotelementet, representerer en sjanger i databasen. 
 <Name>Debatt</Name> // navnet på sjangeren. 
 <Speech-list length="1"> // liste med taler (kronologisk) på denne sjangeren, (1 tale). 
 <Speech id="148"> 
 <Title>Hagens Levende Ord tale</Title> 
 <Location>Bergen</Location> 
 <Event>Sommerfestival</Event> 
 <Date> 
 <Day /> 
 <Month>7</Month> 
 <Year>1990</Year> 
 </Date> 
 <Person id="103"> 
 <Name> 
 <First>Carl Ivar</First> 
 <Last>Hagen</Last> 
 </Name> 
 </Person> 
 </Speech> 
 </Speech-list> 
 </Genre>

Søkefunksjoner

Det finnes to søke­funksjon­er, en enkel og en avansert. Begge funksjonene søk­er etter nøkkelord i forskjel­lige sted­er av data­basen spe­si­fis­ert ved hjelp av flere parametre.

Esok

Fore­tar et søk i data­basen basert på de gitte para­me­trene, og returner­er tal­ene som blir fun­net i søket. Det blir alt­så kun søkt på taler. ESok står for enkelt søk.

Denne funksjo­nen leser to para­me­tere, sok og kat­e­gori. Sok innehold­er søkestren­gen, mens kat­e­gori innehold­er kat­e­gorien det søkes på. Kat­e­gori­er det kan søkes på er:

• alle (søk­er på alle kat­e­goriene under.
• tit­tel (søk­er i tal­enes tittel.)
• taler (søk­er på tale­hold­er til talene.)
• sted (søk­er på stedet tal­en er holdt.)
• aar (søk­er på årstal­let til talene.)
• emne (søk­er i emnene til talene.)
• sjanger (søk­er i sjan­grene til talene.)
• fritekst (søk­er i selve talen.)

Når en søk­er på aar, må årstal­let være fire sif­fer. En kan opp­gi flere år, adskilt med mel­lom, og inter­vall med adskilt strek, eks: ‘1968 1948 1970–1979 1978’. En vil nå søke etter taler i 1968, 1948 og på hele 70-tal­let, merk at årstal­lene i inter­val­lene er inklu­siv. Merk også at en kan opp­gi 1978 selv om dette året er inklud­ert i inter­val­let. Taler holdt 1978 vil nå bli vist først i søk­ere­sul­tatet. En kunne like gjerne søkt på ‘1979–1970’ som ‘1970–1979’.

Tal­ene blir sortert i denne rekkefølgen:

• vekt
• dato (kro­nol­o­gisk, eld­ste først)
• talers etter­navn
• talers for­navn
• id

Vek­ten blir reg­net ut på bak­grunn av hvor godt en tale pas­set med søkekriteriene.

Eksem­pel: http://aurora.uib.no/vo/api/1/Esok?sok=islam&kategori=alle

XML-struk­tur:

<?xml version="1.0" encoding="UTF-8" ?> 
 <Search-result length="1"> // rotelement, totalt antall taler funnet; 1. 
 <Time>0,192</Time> // søketid i sekunder (med millisekundpresisjon). 
 <Query> // søkinfo. 
 <Category>alle</Category> // kategorien det er søkt på. 
 <Term>islam</Term> // søketermen (søkestrengen). 
 </Query> 
 <Exact-hit length="0" /> // liste over taler som traff eksakt på søkekriteriene, her 0. 
 <Partial-hit length="1"> // liste over taler som traff delvis på søkekriteriene, her 1. 
 <Speech id="148"> // talen. 
 <Weight>10</Weight> // vekten som blir regnet ut basert på 
 <Title>Hagens Levende Ord tale</Title> 
 <Location>Bergen</Location> 
 <Event>Sommerfestival</Event> 
 <Date> 
 <Day /> 
 <Month>7</Month> 
 <Year>1990</Year> 
 </Date> 
 <Keyword-list length="3"> // emner for talen. 
 <Keyword id="82">Islam</Keyword> 
 <Keyword id="83">Israel</Keyword> 
 <Keyword id="102">Religion</Keyword> 
 </Keyword-list> 
 <Genre-list length="1"> // sjangre for talen. 
 <Genre id="41">Debatt</Genre> 
 </Genre-list> 
 <Person id="103"> 
 <Name> 
 <First>Carl Ivar</First> 
 <Last>Hagen</Last> 
 </Name> 
 </Person> 
 </Speech> 
 </Partial-hit> 
 <Full-text-hit length="0" /> // liste over taler som traff i fritekstsøk, her 0. 
 </Search-result>

Taler som traff eksakt på minst ett av søkekri­te­riene kom­mer under ele­mentet ‘Exact-hit’.
Taler som traff delvis på minst ett av søkekri­te­riene kom­mer under ele­mentet ‘Par­tial-hit’.
Taler som traff i fritek­st­søk kom­mer under ele­mentet ‘Full-text-hit’.

En tale kan kun opp­tre under én liste, og ‘Exact-hit’ pri­or­iteres foran ‘Par­tial-hit’, og ‘Par­tial-hit’ pri­or­iteres foran ‘Full-text-hit’. Alt­så taler som kom­mer under ‘Full-text-hit’
er taler der søkestren­gen kun traff i fritekst.

Det spiller en rolle hvilken kat­e­gori det søkes på. Hvis det kun søkes på fritekst så vil alle tre­f­fene komme under ‘Full-text-hit’. Hvis det ikke søkes på fritekst så vil ingen tre­ff komme under ‘Full-text-hit’. Hvis det søkes på kat­e­gorien alle, så gjelder de reg­lene som er nevnt over.

Når en fore­tar et søk, blir søkestren­gen delt opp i en liste med søke­ord, og det er disse søke­or­dene det blir søkt på. Alt­så hvis en opp­gir søkestren­gen ‘carl i hagen’ så vil en søke på ‘carl’, ‘i’ og ‘hagen’. Fak­tisk vil en søke på ‘%carl%’, ‘%i%’ og ‘%hagen%’ der % = et vilkårlig antall tegn (null eller flere).

Det som menes med eksakt tre­ff er der­for at et av søke­or­dene tre­f­fer eksakt et av attrib­ut­tene til en tale (avhengig av kat­e­gori). F. eks. vil taler av Carl I. Hagen tre­ffe eksakt hvis en har søkt på kat­e­gorien taler, mens alle taler av talere med en ‘i’ i navnet, vil tre­ffe delvis.

Det blir bare skrevet ut emneliste og sjangerliste hvis søkestren­gen tre­f­fer på et emne og det er søkt på kat­e­gorien ’emne’, ‘sjanger’ eller ‘alle’. Hvis dette ikke er til­fel­let blir det skrevet:

<Key­word-list length=“0”/>
<Genre-list length=“0”/>

selv om tal­en har emn­er og sjangre.

Asok

Fore­tar et søk i data­basen basert på de gitt para­me­trene, og skriv­er ut tal­ene som blir fun­net i søket. Det blir alt­så kun søkt på taler. ASok står for avansert søk.

Funksjo­nen har føl­gende parametre:

• tit­tel (søkestreng for tal­enes tittel.)
• taler (søkestreng for tale­hold­er til talene.)
• sted (søkestreng for stedet tal­en er holdt.)
• aar (søkestreng for årstall til talene.)
• emne (søkestreng for emnene til talene.)
• sjanger (søkestreng for sjan­grene til talene.)
• fritekst (søkestreng for selve talen.)
• og (0= ‘AND’, 1= ‘OR’ ved søk.)
• fuzzy (0=non-fuzzy, 1=fuzzy)
• eksak­tf (bruk­er eksakt søk på fritekst i stedet for fuzzy som er standard)
• eksak­tm (bruk­er eksakt søk på meta­da­ta i stedet for delvis-søk som er standard)

http://aurora.uib.no/vo/api/1/Asok?tittel=arbeid&sted=stortinget&og=1

XML-struk­tur:

<?xml version="1.0" encoding="UTF-8" ?> 
 <Search-result length="0"> 
 <Time>0,185</Time> 
 <Query> 
 <tittel>x</tittel> // søkestreng for tittel 
 <taler>x</taler> // søkestreng for taleholder 
 <sted>x</sted> // søkestreng for sted 
 <aar>x</aar> // søkestreng for årstall 
 <emne>x</emne> // søkestreng for emne 
 <sjanger>x</sjanger> // søkestreng for sjanger 
 <fritekst>x</fritekst> // søkestreng for fritekstsøk. 
 <og>on</og> // enten on eller off, avhengig om parameteren 1 ble oppgitt.
 <fuzzy>off</fuzzy> // enten on eller off
 <eksaktm>off</eksaktm> // enten on eller off
 </Query> 
 <Exact-hit length="0" /> 
 <Partial-hit length="0" /> 
 <Full-text-hit length="0" /> 
 </Search-result>

Spe­si­fikasjonene for Asok er de samme som for Esok bort­sett fra at man ved Asok kan spe­si­fis­ere en søkestreng for hver kat­e­gori. Ved å bruke para­me­teren og kan man også spe­si­fis­ere om man vil bruke bool­sk AND eller OR som skille mel­lom de forskjel­lige søkestrengene.