Nättjänst | Språkbanken

Introduktion

Korps nättjänst, som till största delen är ett gränssnitt till CQP, används för att hämta information ur Språkbankens korpusar. Nättjänsten ligger på adressen:

http://spraakbanken.gu.se/ws/korp

Anrop

Frågor till nättjänsten görs genom GET-anrop:

http://spraakbanken.gu.se/ws/korp?command=...&corpus=...&...

Svaret kommer i form av ett JSON-objekt, vilket visas som text i webbläsaren.

Kommandon som stöds av nättjänsten

Nedan följer en förteckning över de kommandon som stöds av nättjänsten, och vilka argument som accepteras. Argumenten för varje kommando presenteras som en punktlista. När det står

a = ...
[opt] q = "XF"
[multi] x = ...

så betyder det dels att q är optionellt, dels att x kan ta flera värden separerade med kommatecken, dels att URL:en blir:

?a=...&q=XF&x=...,...

Följande argument kan användas vid samtliga frågor:

[opt] encoding = <Teckenkodning för att kommunicera med CQP. Default är UTF-8.>
[opt] indent = <Indentering av det strukturerade resultatet för att göra det mer lättläst. Default är att returnera en kompakt JSON-representation utan indentering.>
[opt] callback = <En sträng som returneras runt JSON-objektet, ibland nödvändigt vid AJAX-anrop.>

Om något blir fel (t.ex. icke-existerande kommando, icke-existerande korpus eller syntaxfel i CQP-uttrycket) så returneras följande:

    {
      "ERROR": {
        "type": <feltyp>, 
        "value": <felmeddelande>
      }
    }

Dessutom returneras alltid ett tidsvärde i JSON-objektet:

    {
      "time": <antal sekunder det tog för skriptet att exekvera (realtid, inte CPU-tid)>
    }

Allmän information

Hämtar information om vilka korpusar som finns på servern och vilken version av CQP som används.

[opt] command = "info"

Returnerar

    {
      "corpora": [<lista med korpusnamn på servern>],
      "cqp-version": <versionsnummer för CQP>
    }

Exempel

?command=info

Korpusinformation

Hämtar information om en eller flera korpusar och tillhörande attribut.

[opt] command = "info"
[multi] corpus = <korpusnamn i versaler>

Returnerar

    {
      "corpora": {
        <korpusnamn>: {
          "attrs": {
            "p": [<lista med positionella attribut>],
            "s": [<lista med strukturella attribut>],
            "a": [<lista med align-attribut, för länkade korpusar>]
          },
          "info": {
            "Charset": <korpusens teckenkodning>,
            "Size": <antal tokens i korpusen>,
            "Sentences": <antal meningar i korpusen>,
            "Updated": <datum för senaste uppdatering>
          }
        }
      "total_size": <totalt antal tokens i korpusarna ovan>,
      "total_sentences": <totalt antal meningar i korpusarna ovan>
      }
    }

Exempel

?command=info&corpus=ROMI,PAROLE

Konkordans

Utför konkordanssökning i en eller flera korpusar.

[opt] command = "query"
[multi] corpus = <korpusnamn i versaler>
cqp = <CQP-uttryck>
start = <startrad>
end = <slutrad>
[opt] defaultcontext = <kontext som visas>
[opt, multi] context = <kontext som visas för specifik korpus i stället för default, anges som 'korpusnamn:kontext'>
[opt, multi] show = <positionella attribut som ska visas>
[opt, multi] show_struct = <strukturella attribut som ska visas>
[opt] cut = <hur många resultat som max ska sökas på>
[opt] defaultwithin = <begränsa sökningen till inom angivet strukturellt attribut>
[opt, multi] within = <som ovan men för specifik korpus i stället för default, anges som 'korpusnamn:attribut'>
[opt] sort = <sortera sökresultaten inom varje korpus på sökord ('keyword'), vänster- ('left') eller högerkontext ('right'), eller slumpvis ('random')>
[opt] random_seed = <numeriskt värde för reproducerbar slumpsortering (används optionellt tillsammans med sort=random ovan)>
[opt] incremental = <returnerar resultatet inkrementellt om satt till 'true' och flera korpusar används>

Även om man inte anger "show=word" så visas ordet i konkordansen.

Returnerar

    {
      "hits": <totala antalet träffar>,
      "corpus_hits": {
        <korpus>: <antalet träffar>,
        ...
      }
      "kwic": [
        <första konkordansraden>,
        {
          "match": {
            "start": <startposition inom raden>,
            "end": <slutposition inom raden>,
            "position": <globala korpuspositionen för träffen>,
          },
          "tokens: [
            <första token i träffraden>,
            {
              "word": <ordform>,
              "pos": <pos-attributet>,
              "saldo": <saldo-attributet>,
              ...
            }
            <tredje token i träffraden>,
            ...
          ],
          <om det ingår länkade korpusar>
          "aligned": {
            <alignad korpus>: [<lista med tokens>], ...
          }
        },
        <tredje konkordansraden>,
        ...
      ]
    }

Exempel som visar de 10 första meningarna/länkarna som matchar CQP-frågan: "och" [] [pos="NN"]

Frågar SUC2 och visar ordklass + grundform:

?command=query&corpus=SUC2&start=0&end=9&defaultcontext=1+sentence&cqp="och"+[]+[pos="NN"]&show=msd,lemma

Frågar SALTNLD_SWE och visar ordklass + den länkade nederländska texten:

?command=query&corpus=SALTNLD_SWE&start=0&end=9&context=1+link&cqp="och"+[]+[pos="NN"]&show=saltnld_nld

Ordbild

Givet ett lemgram eller ett ord hämtas vanliga dependensrelationer detta förekommer i.

command = "relations"
[multi] corpus = <korpusnamn i versaler>
word = <det lemgram eller den ordform man vill slå upp>
[opt] type = <söktyp: 'word' (standard) eller 'lemgram'>
[opt] min = <lägsta önskade frekvens>
[opt] max = <max antal resultat>
[opt] incremental = <returnerar inkrementellt information om när beräkningen är färdig för varje enskild korpus>

Returnerar

    {
      "relations": [
        {
          "corpus": [
            <lista med korpusar i vilka träffar hittades>
          ], 
          "dep": <dependent-lemgram>,
          "depextra": <dependent-prefix>,
          "freq": <antal förekomster>,
          "head": <huvud-lemgram>,
          "mi": <lexicographer's mutual information-värde>,
          "rel": <relation>
        }, 
        ...
      ]
    }

Exempel som hämtar dependensrelationer för lemgrammet ge..vb.1

?command=relations&word=ge..vb.1&type=lemgram&corpus=ROMI

Ordbildsförekomster

Givet information om en dependensrelation (förslagsvis taget från en ordbildfråga ovan) hämtas de meningar i vilka denna relation förekommer.

command = "relations_sentences"
[multi] corpus = <korpusnamn i versalen>
head = <huvud-lemgram>
rel = <relation>
[opt] dep = <dependent-lemgram>
[opt] depextra = <dependent-prefix>
[opt] start = <startrad>
[opt] end = <slutrad>

Returnerar

Returnerar en likadan struktur som för en vanlig konkordansfråga beskriven ovan.

Exempel som hämtar alla meningar innehållande dependensrelationen (ge..vb.1, SS, instruktion..nn.1)

?command=relations_sentences&corpus=ROMI&head=ge..vb.1&dep=instruktion..nn.1&rel=SS

Statistik

Beräknar frekvensen för ett eller flera attribut givet en CQP-fråga. Både absolut och relativ frekvens ges.

command = "count"
cqp = <cqp-uttryck>
[multi] groupby = <positionella och/eller strukturella attribut efter vilkas värden träffarna ska grupperas>
[multi] corpus = <korpusnamn i versaler>
[opt] defaultwithin = <begränsa sökningen till inom angivet strukturellt attribut>
[opt, multi] within = <som ovan men för specifik korpus i stället för default, anges som 'korpusnamn:attribut'>
[opt] ignore_case = <attribut för vilka skiftläge ska ignoreras>
[opt] incremental = <returnerar inkrementellt information om när beräkningen är färdig för varje enskild korpus>

Returnerar

    {
      "corpora": {
        <korpus>: {
          "absolute": {
            <attribut1/attribut2/attribut3/...>: <absolut frekvens>,
            ...
          }, 
          "relative": {
            <attribut1/attribut2/attribut3/...>: <relativ frekvens>,
            ...
          },
          "sums": {
            "absolute": <absolut summa>, 
            "relative": <relativ summa>
          }
        },
      }, 
      "total": {
        "absolute": {
          <attribut1/attribut2/attribut3/...>: <absolut frekvens>,
          ...
        }, 
        "relative": {
          <attribut1/attribut2/attribut3/...>: <relativ frekvens>,
          ...
        },
        "sums": {
          "absolute": <absolut summa>, 
          "relative": <relativ summa>
        }
      }
      "count": <totalt antal olika värden>
    }

Exempel som returnerar frekvenser för de olika ordformerna av lemgrammet ge..vb.1

?command=count&corpus=ROMI&cqp=[lex+contains+"ge..vb.1"]&groupby=word&ignore_case=word

Lemgramstatistik

Beräknar antalet förekomster av ett eller flera lemgram i en eller flera korpusar.

command = "lemgram_count"
[multi] lemgram = <lemgram att söka efter>
[opt, multi] corpus = <korpusnamn i versaler (om utelämnas: alla korpusar)>
[opt] count = <räkna vanliga förekomster ('lemgram'), förekomster som förled ('prefix'), eller förekomster som efterled ('suffix')>
[opt] incremental = <returnerar inkrementellt information om när beräkningen är färdig för varje enskild korpus>

Returnerar

    {
      "<lemgram>": <förekomster>, 
    }

Exempel som returnerar antalet förekomster av lemgrammet ge..vb.1

?command=lemgram_count&lemgram=ge..vb.1&corpus=ROMI

Log-likelihood-jämförelse

Jämför sökresultaten mellan två uppsättningar korpusar med hjälp av log-likelihood.

command = "loglike"
cqp = <cqp-uttryck>
[multi] groupby = <positionella och/eller strukturella attribut efter vilkas värden träffarna ska grupperas>
[multi] set1 = <korpusnamn i versaler>
[multi] set2 = <korpusnamn i versaler>
[opt] max = <maximalt antal resultat>
[opt] incremental = <returnerar inkrementellt information om när beräkningen är färdig för varje enskild korpus>

Returnerar

    {
      "average": <medelvärde för log-likelihood>,
      "loglike": {
        "<värde>": <log-likelihood-värde>,
        ...
      },
    }

Positivt log-likelihood-värde indikerar en relativ ökning i set2 jämfört med set1, medan negativt indikerar en relativ minskning.

Exempel som jämför substantiven i två olika korpusar

?command=loglike&cqp=[pos="NN"]&groupby=word&max=10&set1=ROMI&set2=GP2012