Mörkun POS tagging

Þjónustan postag.api tekur inn texta og skilar til baka hverju orði hans með ítarlegri mörkun (part-of-speech tag), þ.e. upplýsingum um orðflokk, stofn, beygingu o.fl. Einnig fylgir með nafnalisti yfir fólk og fyrirbæri með sérnöfn.

Stutta texta sem eru einungis ein málsgrein má málgreina með einföldu HTTPS GET þar sem textinn er sendur sem hluti af vefslóð (URL):

GET https://greynir.is/postag.api/v1?t=Hér er dæmi um texta til að málgreina

Lengri texta má senda með HTTP POST í application/x-www-form-urlencoded formi, í svæði sem heitir text.

Dæmi um hvernig nota má POST kallið frá curl í GNU/Linux:

$ curl -d "text=Í dag er ágætt veður en mikil hálka er á götum." https://greynir.is/postag.api/v1

Enn lengri texta má senda með HTTP POST í text/plain formi, kóðaða í UTF-8 og með línuskiptum (newline, \n) milli málsgreina. Dæmi:

$ curl -d @example.txt https://greynir.is/postag.api/v1 --header "Content-Type: text/plain"

postag.api/v1 þjónustan skilar JSON skjali með eftirfarandi undirgreinum:

• result er listi af málsgreinum þar sem hver málsgrein er aftur listi af eindum (tokens). Hver eind innifelur eftirfarandi upplýsingar:
  • k er tegund eindar, þ.e. WORD, PERSON, PUNCTUATION, YEAR, AMOUNT o.s.frv.
  • x er upphaflegur texti eindarinnar eins og hann var í innsendu skjali.
  • s er orðstofn. Hann getur innihaldið bandstrik '-' ef stofninn er ekki í BÍN og Greynir hefur notast við samsettan orðstofn.
  • c er orðflokkur (kk/kvk/hk, so, lo, ao, fs, st o.s.frv.).
  • b er beygingarform orðsins eins og það birtist í BÍN. Getur verið bandstrik '-' ef orðið er óbeygt.
  • t er lauf (terminal) sem eindin tengist í samhengisfrjálsri málfræði Greynis.
  • v er gildi eindarinnar ef við á, til dæmis tala, upphæð, dagsetning eða nafn gjaldmiðils.
  • f er flokkur í BÍN (alm, ism, fyr, örn o.s.frv.).
  Ef ekki tekst að greina málsgrein eru aðeins svæði k og x fyrir hendi í eindum hennar. Jafnframt er sú eind þar sem málgreinirinn gafst upp merkt með svæði err sem hefur gildið 1. Þar fannst engin málfræðiregla sem leyfði viðkomandi eind á þeim stað. Ástæðan er þá annað hvort sú að einhverju sé ábótavant í málfræði eða stafsetningu málsgreinarinnar, eða að málfræðireglur Greynis séu ekki nógu víðtækar.
• register er nafnalisti
• stats er samantekt af tölfræði, m.a. fjölda málsgreina og einda í textanum:
  • ambiguity er margræðnistuðull, skilgreindur sem vegið meðaltal af (fjölda trjágreininga)^(1/(fjölda einda)) fyrir allar málsgreinar í textanum. Stuðullinn gefur m.ö.o. til kynna hvernig mögulegum trjágreiningum fjölgar við hverja viðbótar eind í textanum. Algengur stuðull er á bilinu 1,5 - 1,6. Ef hann er hærri er textinn óvenju margræður af einhverjum orsökum, t.d. gætu verið margir mismunandi möguleikar á að tengja forsetningarliði við nafnliði og sagnliði. Ef stuðullinn er 1 finnst aðeins ein möguleg trjágreining á textanum og margræðni því engin.
  • num_sentences er fjöldi málsgreina í textanum.
  • num_parsed er fjöldi málsgreina í textanum sem tókst að trjágreina.
  • num_tokens er fjöldi einda í textanum. Allar eindir sem Greynir þekkir eru taldar með. Greynir sleppir hins vegar ýmsum táknum sem hann þekkir ekki.
  • parse_time er tími, í sekúndum, sem þáttun (parsing) tók. Hver fyrirspurn er höndluð í einum þræði, en Greynir getur unnið að mörgum fyrirspurnum samtímis.
  • tok_time er tími, í sekúndum, sem eindagreining (tokenization) tók.
  • total_time er heildartími, í sekúndum, sem úrvinnsla textans tók. Summa af tok_time og parse_time.

Dæmi um mörkun málsgreinarinnar Halldór Laxness fékk nóbelsverðlaunin í bókmenntum árið 1955.

{
  "register": {
    "Halldór Laxness": {
      "kind": "name", 
      "title": "rithöfundur"
    }
  }, 
  "result": [
    [
      {
        "c": "kk",
        "k": "PERSON",
        "t": "person_nf_kk", 
        "s": "Halldór Laxness", 
        "x": "Halldór Laxness"
      }, 
      {
        "b": "GM-FH-ÞT-3P-ET", 
        "c": "so", 
        "f": "alm", 
        "k": "WORD", 
        "s": "fá", 
        "t": "so_1_þf_et_p3", 
        "x": "fékk"
      }, 
      {
        "b": "ÞFFTgr", 
        "c": "hk", 
        "f": "alm", 
        "k": "WORD", 
        "s": "nóbelsverðlaun", 
        "t": "no_ft_þf_hk", 
        "x": "nóbelsverðlaunin"
      }, 
      {
        "b": "ÞGF", 
        "c": "fs", 
        "f": "alm", 
        "k": "WORD", 
        "s": "í", 
        "t": "fs_þgf", 
        "x": "í"
      }, 
      {
        "b": "ÞGFFT", 
        "c": "kvk", 
        "f": "alm", 
        "k": "WORD", 
        "s": "bókmennt", 
        "t": "no_ft_þgf_kvk", 
        "x": "bókmenntum"
      }, 
      {
        "b": "ÞFETgr", 
        "c": "hk", 
        "f": "alm", 
        "k": "WORD", 
        "s": "ár", 
        "t": "no_gr_et_þf", 
        "x": "árið"
      }, 
      {
        "k": "YEAR", 
        "t": "ártal", 
        "v": 1955, 
        "x": "1955"
      }, 
      {
        "k": "PUNCTUATION", 
        "x": "."
      }
    ]
  ], 
  "stats": {
    "ambiguity": 1.0905077326652577, 
    "num_parsed": 1, 
    "num_sentences": 1, 
    "num_tokens": 8, 
    "parse_time": 0.18756818771362305, 
    "tok_time": 0.019917011260986328, 
    "total_time": 0.20748519897460938
  }
}

Þjónustan ifdtag.api tekur inn texta og skilar til baka hverju orði hans með einfaldri mörkun (part-of-speech tag) úr markaskrá Íslensku orðtíðnibókarinnar (IFD).

ifdtag.api notar markara sem byggir á tölfræði úr stóru textasafni, ekki á málfræðireglum. Þjónustan getur því markað texta sem Greyni tekst ekki að þátta. Á móti kemur að nákvæmnin er tilviljanakenndari og samkvæmni stundum minni en í postag.api sem byggir á þáttun.

Stutta texta sem eru einungis ein málsgrein má málgreina með einföldu HTTPS GET þar sem textinn er sendur sem hluti af vefslóð (URL):

GET https://greynir.is/ifdtag.api/v1?t=Hér er dæmi um texta til að málgreina

Lengri texta má senda með HTTP POST í application/x-www-form-urlencoded formi, í svæði sem heitir text.

Dæmi um hvernig nota má POST kallið frá curl í GNU/Linux:

$ curl -d "text=Í dag er ágætt veður en mikil hálka er á götum." https://greynir.is/ifdtag.api/v1

Enn lengri texta má senda með HTTP POST í text/plain formi, kóðaða í UTF-8 og með línuskiptum (newline, \n) milli málsgreina. Dæmi:

$ curl -d @example.txt https://greynir.is/ifdtag.api/v1 --header "Content-Type: text/plain"

ifdtag.api/v1 þjónustan skilar JSON skjali með eftirfarandi undirgreinum:

• result er listi af málsgreinum þar sem hver málsgrein er aftur listi af eindum (tokens). Hver eind er listi með tveimur stökum:
  • [0] Upphaflega orðið eins og það kom fyrir í textanum
  • [1] Mark orðsins skv. markaskrá Íslensku orðtíðnibókarinnar
• valid er true ef mörkun tókst, annars false

Dæmi um mörkun málsgreinarinnar Halldór Laxness fékk nóbelsverðlaunin í bókmenntum árið 1955.

{
  "result": [
    [
      [
        "Halldór", 
        "nken-m"
      ], 
      [
        "Laxness", 
        "nken-m"
      ], 
      [
        "fékk", 
        "sfg3eþ"
      ], 
      [
        "nóbelsverðlaunin", 
        "nhfog"
      ], 
      [
        "í", 
        "aþ"
      ], 
      [
        "bókmenntum", 
        "nvfþ"
      ], 
      [
        "árið", 
        "nheog"
      ], 
      [
        "1955", 
        "ta"
      ], 
      [
        ".", 
        "."
      ]
    ]
  ], 
  "valid": true
}

Fyrirspurnir

Þjónustan query.api svarar fyrirspurnum um fólk og titla og um skilgreiningar sérnafna. Einnig er unnt að spyrja um orð sem tengjast gefnum orðum.

Nánar til tekið má spyrja um eftirfarandi:

• Mannanöfn: Hver er Smári McCarthy? / Segðu mér frá Oddnýju G. Harðardóttur
• Titla: Hver er forstjóri Útlendingastofnunar? / Hver gegnir starfi Seðlabankastjóra?
• Sérnöfn: Hvað er WHO?
• Tengsl orða: Hvað tengist orðinu gagnaver?

Einfaldast er að senda fyrirspurn með HTTPS GET þar sem hún er hluti af vefslóð (URL):

GET https://greynir.is/query.api/v1?q=Fyrirspurnin kemur hér

Fyrirspurn má einnig senda með HTTP POST í application/x-www-form-urlencoded formi, í svæði sem heitir q.

Dæmi um hvernig nota má POST kallið frá curl í GNU/Linux:

$ curl -d "q=Hver er bankastjóri Landsbankans?" https://greynir.is/query.api/v1

query.api/v1 þjónustan skilar JSON skjali með eftirfarandi undirgreinum:

• valid er true ef fyrirspurnin er gild, annars false.
• key er lykillinn sem leitað var eftir í gagnagrunni Greynis.
• q er upphaflega fyrirspurnin.
• qtype er tegund fyrirspurnar, þ.e. Title (titill), Person (mannsnafn), Entity (sérnafn) eða Word (tengd orð).
• response er niðurstaða fyrirspurnarinnar. Hún er mismunandi eftir tegundum:
  • Title: listi af nöfnum þeirra sem bera titilinn. Hvert stak í listanum inniheldur:
    • answer er nafn
    • sources er listi yfir heimildir, þar sem hvert stak inniheldur:
      • domain er lén heimildarinnar, t.d. ruv.is
      • heading er fyrirsögn heimildarinnar
      • ts er tímastimpill heimildarinnar á ISO formi (YYYY-MM-DDTHH:MM)
      • url er vefslóð heimildarinnar
      • uuid er einkvæmt einkenni heimildarinnar (UUID) í grunni Greynis
  • Person: Tvö undirsvæði:
    • answers er listi yfir titla fólks með því nafni sem spurt var um. Hvert stak inniheldur:
      • answer er titill
      • sources er listi yfir heimildir, sbr. Title hér að ofan.
    • sources er listi yfir greinar þar sem nafnið kemur fyrir, sbr. Title hér að ofan.
  • Entity: Niðurstaða er eins og fyrir Person, nema hvað í stað titla koma skilgreiningar á sérnafninu sem spurt var um.
  • Word: Eitt undirsvæði:
    • answers er listi yfir tengd orð, þar sem hvert stak inniheldur:
      • stem er orðstofn tengds orðs
      • cat er orðflokkur tengds orðs

Dæmi um svar við fyrirspurninni Hver er dómsmálaráðherra Bretlands?

{
   "valid": true, 
   "key": "dómsmálaráðherra Bretlands", 
   "num_parsed_sent": 1, 
   "num_sent": 1, 
   "q": "Hver er dómsmálaráðherra Bretlands?", 
   "qtype": "Title", 
   "response": [
     {
       "answer": "Michael Gove", 
       "sources": [
         {
           "domain": "mbl.is", 
           "heading": "Theresa May sigraði í fyrstu umferð", 
           "ts": "2016-07-05T20:42", 
           "url": "http://www.mbl.is/frettir/erlent/2016/07/05/theresa_may_sigradi_i_fyrstu_umferd/", 
           "uuid": "2133214a-4533-11e6-8429-04014c605401"
         }, 
         {
           "domain": "ruv.is", 
           "heading": "Sækjast eftir að stýra Íhaldsflokknum", 
           "ts": "2016-06-30T09:28", 
           "url": "http://www.ruv.is/frett/saekjast-eftir-ad-styra-ihaldsflokknum", 
           "uuid": "1f86a9f2-4533-11e6-8429-04014c605401"
         }, 
         {
           "domain": "mbl.is", 
           "heading": "Johnson, Gove og May bítast um formanninn", 
           "ts": "2016-06-30T08:18", 
           "url": "http://www.mbl.is/frettir/erlent/2016/06/30/johnson_gove_og_may_bitast_um_formanninn/", 
           "uuid": "1ee101df-4533-11e6-8429-04014c605401"
         }
       ]
     }
   ]
}

Greinar

Þjónustan article.api skilar upplýsingum um tiltekna grein eða frétt í gagnagrunni Greynis, m.a. sérnöfnum, nöfnum og titlum fólks sem kemur fyrir í greininni, og efnisflokkum greinarinnar.

Sækja má grein eftir vefslóð (URL) eða einkenni hennar í gagnagrunni Greynis (UUID).

Spyrja má um grein með HTTPS GET ásamt url eða id:

GET https://greynir.is/article.api/v1?url=Vefslóð kemur hér

eða:

GET https://greynir.is/article.api/v1?id=Einkenni (UUID) kemur hér

Sama gildir um HTTP POST í application/x-www-form-urlencoded formi.

Dæmi um hvernig nota má POST kallið frá curl í GNU/Linux:

$ curl -d "url=http://www.ruv.is/frett/segir-nafn-svavars-gudnasonar-eydilagt" https://greynir.is/article.api/v1

article.api/v1 þjónustan skilar JSON skjali með eftirfarandi undirgreinum:

• valid er true ef beiðnin er gild, annars false.
• author er höfundur greinarinnar, ef hann er þekktur.
• heading er fyrirsögn greinarinnar.
• id er einkvæmt einkenni (UUID) greinarinnar í gagnagrunni Greynis.
• url er vefslóð greinarinnar.
• ts er tímastimpill greinarinnar, á ISO formi (YYYY-MM-DDTHH:MM:SS).
• num_sentences er fjöldi málsgreina í greininni.
• num_parsed er fjöldi málsgreina sem Greyni tókst að þátta.
• register er nafnalisti sem inniheldur undirskjöl með nafni fólks og sérnöfnum sem koma fyrir í greininni. Í hverju undirskjali eru eftirfarandi undirgreinar:
  • kind getur verið entity (sérnafn) eða name (mannsnafn).
  • title er titill manns eða skilgreining sérnafns. Ef titill eða skilgreining eru ekki þekkt er gildið null.
• topics er listi yfir efnisflokka sem greinin heyrir undir. Hver eind í listanum inniheldur eftirfarandi:
  • id er einkenni efnisflokksins, svo sem culture, sport eða economy.
  • name er íslenskt heiti efnisflokksins, svo sem Menning og listir, Íþróttir eða Efnahagsmál.

Dæmi um upplýsingar um greinina http://www.ruv.is/frett/segir-nafn-svavars-gudnasonar-eydilagt

{
  "ambiguity": 1.58401878459231, 
  "author": "Sigríður Hagalín Björnsdóttir", 
  "heading": "Segir nafn Svavars Guðnasonar eyðilagt", 
  "id": "e3701936-bc78-11e6-b57e-04014c605401", 
  "num_parsed": 16, 
  "num_sentences": 17, 
  "register": {
    "Bruun Rasmussen": {
      "kind": "entity", 
      "title": "danskt uppboðshús"
    }, 
    "Svavar Guðnason": {
      "kind": "name", 
      "title": "abstraktlistamaður"
    }, 
    "Ólafur Ingi Jónsson": {
      "kind": "name", 
      "title": "forvörður hjá Listasafni Íslands"
    }
  }, 
  "topics": [
    {
      "id": "culture", 
      "name": "Menning og listir"
    }
  ], 
  "ts": "2016-12-07T12:20:02", 
  "url": "http://www.ruv.is/frett/segir-nafn-svavars-gudnasonar-eydilagt", 
  "valid": true
}