University of Gothenburg Statistics API

openapi: 3.2.0
info:
  title: University Of Gothenburg Statistics API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Statistics across 2 of this provider''s published API definitions: university-of-gothenburg-karp-api-openapi.json, university-of-gothenburg-korp-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /karp/v7
- url: https://ws.spraakbanken.gu.se/ws/korp/v8
tags:
- name: Statistics
paths:
  /stats/{resource_id}/{field}:
    get:
      tags:
      - Statistics
      summary: Get Field Values
      description: Return all possible values for `` in ``
      operationId: get_field_values_stats__resource_id___field__get
      security:
      - APIKeyQuery: []
      parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          title: Resource Id
      - name: field
        in: path
        required: true
        schema:
          type: string
          title: Field
      - name: authorization
        in: header
        required: false
        schema:
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StatisticsDto'
                title: Response Get Field Values Stats  Resource Id   Field  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: /karp/v7
  /count:
    get:
      summary: Statistics
      description: 'Given a CQP query, calculate the frequency for one or more attributes. Both absolute and relative frequency are calculated. The relative frequency is given as *hits per 1 million tokens*.


        For instances when you want to calculate statistics for *every* token in one or several corpora, the `/count_all` command should be used instead since it is optimized for that kind of query.


        If you want to base your statistics on one single token in a multi token query, prefix that token with an `@`, e.g. `[pos = "JJ"] @[pos = "NN"]`.


        When `subcqp#` parameters are used, `""` and `"total"` above will instead each contain a list, with the first item being the result of the main `cqp` query, and the following items the results of the `subcqp#` queries. The `subcqp#` results will each have an additional key, `"cqp"`, containing the CQP query for that particular subquery.


        ### Example


        Get frequencies for the different word forms of the lemgram `ge..vb.1`:

        [`/count?corpus=ROMI&cqp=[lex+contains+"ge..vb.1"]&group_by=word&ignore_case=word`](https://ws.spraakbanken.gu.se/ws/korp/v8/count?corpus=ROMI&cqp=[lex+contains+%22ge..vb.1%22]&group_by=word&ignore_case=word&indent=4)'
      tags:
      - Statistics
      parameters:
      - $ref: '#/components/parameters/Corpus'
      - $ref: '#/components/parameters/CQP'
      - $ref: '#/components/parameters/GroupBy'
      - $ref: '#/components/parameters/GroupByStruct'
      - $ref: '#/components/parameters/DefaultWithin'
      - $ref: '#/components/parameters/Within'
      - $ref: '#/components/parameters/IgnoreCase'
      - name: relative_to_struct
        description: Calculate relative frequencies based on total number of tokens with the same value for the structural annotations specified here, instead of relative to corpus size.
        in: query
        schema:
          type: array
          items:
            type: string
        example:
        - text_author
        explode: false
      - name: split
        description: Attributes that should be split (used for sets).
        in: query
        schema:
          type: array
          items:
            type: string
        example:
        - baseform
        - sense
        explode: false
      - name: top
        description: 'Preserve only the first *n* annotations in a set. Format: ''annotation:n''. If *:n* is omitted only the first value will be preserved. Must be used together with `split`.'
        in: query
        schema:
          type: array
          items:
            type: string
        example:
        - sense:3
        explode: false
      - $ref: '#/components/parameters/CQPn'
      - $ref: '#/components/parameters/ExpandPrequeries'
      - $ref: '#/components/parameters/SubCQPn'
      - name: start
        description: Start row; used for pagination.
        in: query
        schema:
          type: integer
          default: 0
      - name: end
        description: End row; used for pagination. By default no limit.
        in: query
        schema:
          type: integer
        example: 25
      - $ref: '#/components/parameters/IncrementalProgress'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  corpora:
                    type: object
                    description: Statistics per corpus. An object with corpus names as keys, and either objects or arrays of objects as values depending on whether the `subcqp#` parameter is used. When `subcqp#` is used, each value consists of an array with the first item being the result of the main `cqp` query (or the last `cqp#` query), and the following items the results of the `subcqp#` queries. The `subcqp#` results will each have an additional key, `cqp`, containing the CQP query for that particular subquery.
                    additionalProperties:
                      oneOf:
                      - $ref: '#/paths/~1count/get/responses/200/content/application~1json/schema/properties/combined/oneOf/0'
                      - type: array
                        items:
                          $ref: '#/paths/~1count/get/responses/200/content/application~1json/schema/properties/combined/oneOf/0'
                  combined:
                    description: Combined statistics for all corpora. Either an object or an array of objects depending on whether the `subcqp#` parameter is used. When `subcqp#` is used, this will consist of an array with the first item being the result of the main `cqp` query (or the last `cqp#` query), and the following items the results of the `subcqp#` queries. The `subcqp#` results will each have an additional key, `cqp`, containing the CQP query for that particular subquery.
                    oneOf:
                    - type: object
                      properties:
                        sums:
                          type: object
                          properties:
                            absolute:
                              type: integer
                              example: 598
                            relative:
                              type: number
                              example: 13.765536
                        rows:
                          type: array
                          items:
                            type: object
                            properties:
                              absolute:
                                description: Absolute frequency.
                                type: integer
                                example: 598
                              relative:
                                description: Relative frequency.
                                type: number
                                example: 13.765536
                              value:
                                description: An object with annotations as keys. Structural annotations are given as strings, while positional are given as arrays of strings, one string per word in the match.
                                type: object
                                additionalProperties:
                                  anyOf:
                                  - type: string
                                  - type: array
                                    items:
                                      type: string
                    - type: array
                      items:
                        $ref: '#/paths/~1count/get/responses/200/content/application~1json/schema/properties/combined/oneOf/0'
                  count:
                    type: integer
                    description: Total number of different values.
                    example: 241
                  time:
                    $ref: '#/components/schemas/Time'
      security:
      - basicAuth: []
      operationId: getCount
      x-operation-id-source: derived
    servers:
    - url: https://ws.spraakbanken.gu.se/ws/korp/v8
  /count_all:
    get:
      summary: Complete Statistics
      description: 'Same as regular statistics (`/count`) but without specifying `cqp`, resulting in a complete list of every value of the given attributes.


        Takes the same parameters as `/count`, except it doesn''t use `cqp`. Response format is the same.


        ### Example


        Get statistics for all parts of speech in one corpus:

        /count_all?corpus=ROMI&group_by=pos'
      tags:
      - Statistics
      responses:
        '200':
          description: OK
      security:
      - basicAuth: []
      operationId: getCountAll
      x-operation-id-source: derived
    servers:
    - url: https://ws.spraakbanken.gu.se/ws/korp/v8
  /count_time:
    get:
      summary: Statistics Over Time
      description: 'Show the change in frequency of one or more search results over time.


        **Interpreting the results**


        The data points in the result indicates the number of hits *from that point onward* until the next data point, meaning that the following data:


        ```json

        "2010": 100,

        "2012": 50,

        "2013": 0,

        "2016": null

        ```


        should be interpreted as 100 hits during 2010–2011, then 50 hits during 2012, zero hits 2013–2015, and finally from 2016 onwards we have no data at all.


        **Strategies**


        What should happen when you ask for time data with a granularity finer than that of the annotated material? Does a search limited to the period 2005-01-01 -- 2005-01-31 include material dated with only "2005"? The `strategy` parameter gives you some control over this, affecting both how `from` and `to` work, and what parts of the material contribute to the results.


        The list below describes the three different strategies, and for each strategy the rules that decide what part of the material is included in the search, as well as what tokens contribute to the token count for each data point.


        The term "result time span" below refers both to the `from` and `to` span given by the user, and the different time spans making up the data points in the result data, the size of which are determined by the `granularity` parameter. For example the data point "2015" representing the whole of year 2015 when `granularity` is set to ''y'', and "2015-01" representing the whole of January 2015 with `granularity` set to ''m''.


        `t1` and `t2` represents the *from* and *to* dates for an annotated part of the material, and `t1''` and `t2''` is the *from* and *to* of "result time span" described above.


        *Strategy 1*

        The material time span needs to be completely contained by the result time span, or the result time span needs to be

        completely contained by the material time span.

        `(t1 >= t1'' AND t2 = t2'')`


        *Strategy 2*

        All overlaps allowed between material time span and result time span.

        `t1 = t1''`


        *Strategy 3*

        The material time span is completely contained by the result time span.

        `t1 >= t1'' AND t2 <= t2''`


        ### Example


        Show how the use of "tsunami" and "flodvåg" ("tidal wave") has changed over time in the Swedish newspaper Göteborgs-Posten:

        [`/count_time?cqp=[lex+contains+"tsunami\.\.nn\.1|flodvåg\.\.nn\.1"]&corpus=GP2001,GP2002,GP2003,GP2004,GP2005,GP2006,GP2007,GP2008,GP2009,GP2010,GP2011,GP2012&subcqp0=[lex+contains+''tsunami\.\.nn\.1'']&subcqp1=[lex+contains+''flodvåg\.\.nn\.1'']`](https://ws.spraakbanken.gu.se/ws/korp/v8/count_time?cqp=%5Blex+contains+%22tsunami%5C.%5C.nn%5C.1%7Cflodv%C3%A5g%5C.%5C.nn%5C.1%22%5D&corpus=GP2001%2CGP2002%2CGP2003%2CGP2004%2CGP2005%2CGP2006%2CGP2007%2CGP2008%2CGP2009%2CGP2010%2CGP2011%2CGP2012&subcqp0=%5Blex+contains+''tsunami%5C.%5C.nn%5C.1''%5D&subcqp1=%5Blex+contains+''flodv%C3%A5g%5C.%5C.nn%5C.1''%5D&indent=4)'
      tags:
      - Statistics
      parameters:
      - $ref: '#/components/parameters/Corpus'
      - $ref: '#/components/parameters/CQP'
      - $ref: '#/components/parameters/DefaultWithin'
      - $ref: '#/components/parameters/Within'
      - $ref: '#/components/parameters/SubCQPn'
      - $ref: '#/components/parameters/Granularity'
      - $ref: '#/components/parameters/TimeFrom'
      - $ref: '#/components/parameters/TimeTo'
      - name: strategy
        description: Time matching strategy. One of 1 (default), 2 or 3. See section about strategies for explanation.
        in: query
        schema:
          type: integer
          enum:
          - 1
          - 2
          - 3
          default: 1
      - name: per_corpus
        description: Include per-corpus results.
        schema:
          type: boolean
          default: true
        in: query
      - name: combined
        description: Include combined results.
        schema:
          type: boolean
          default: true
        in: query
      - $ref: '#/components/parameters/CQPn'
      - $ref: '#/components/parameters/ExpandPrequeries'
      - $ref: '#/components/parameters/IncrementalProgress'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  corpora:
                    type: object
                    description: Time statistics per corpus. An object with corpus names as keys, and either objects or arrays of objects as values depending on whether the `subcqp#` parameter is used. When `subcqp#` is used, each value consists of an array with the first item being the result of the main `cqp` query (or the last `cqp#` query), and the following items the results of the `subcqp#` queries. The `subcqp#` results will each have an additional key, `cqp`, containing the CQP query for that particular subquery.
                    additionalProperties:
                      oneOf:
                      - $ref: '#/paths/~1count_time/get/responses/200/content/application~1json/schema/properties/combined/oneOf/0'
                      - type: array
                        items:
                          $ref: '#/paths/~1count_time/get/responses/200/content/application~1json/schema/properties/combined/oneOf/0'
                  combined:
                    description: Combined time statistics for all corpora. Either an object or an array of objects depending on whether the `subcqp#` parameter is used. When `subcqp#` is used, each value consists of an array with the first item being the result of the main `cqp` query (or the last `cqp#` query), and the following items the results of the `subcqp#` queries. The `subcqp#` results will each have an additional key, `cqp`, containing the CQP query for that particular subquery.
                    oneOf:
                    - type: object
                      properties:
                        absolute:
                          description: Absolute frequency per time period.
                          type: object
                          additionalProperties:
                            type:
                            - integer
                            - 'null'
                          example:
                            2017: 354
                            2018: 115
                            2019: null
                        relative:
                          description: Relative frequency per time period.
                          type: object
                          additionalProperties:
                            type:
                            - number
                            - 'null'
                          example:
                            2017: 65.265
                            2018: 87.521
                            2019: null
                        sums:
                          type: object
                          properties:
                            absolute:
                              description: Absolute frequency sum.
                              type: integer
                              example: 469
                            relative:
                              description: Relative frequency sum.
                              type: number
                              example: 152.786
                    - type: array
                      items:
                        $ref: '#/paths/~1count_time/get/responses/200/content/application~1json/schema/properties/combined/oneOf/0'
                  time:
                    $ref: '#/components/schemas/Time'
      security:
      - basicAuth: []
      operationId: getCountTime
      x-operation-id-source: derived
    servers:
    - url: https://ws.spraakbanken.gu.se/ws/korp/v8
  /timespan:
    get:
      summary: Distribution Over Time
      description: 'Show the distribution of all tokens in a corpus over time.


        ### Example


        Show distribution of tokens in the Swedish Party Programs and Election Manifestos corpus over time:

        /timespan?corpus=VIVILL'
      tags:
      - Statistics
      parameters:
      - $ref: '#/components/parameters/Corpus'
      - $ref: '#/components/parameters/Granularity'
      - $ref: '#/components/parameters/TimeFrom'
      - $ref: '#/components/parameters/TimeTo'
      - name: strategy
        description: Time matching strategy. One of 1 (default), 2 or 3. See section about strategies for the `/count_time` endpoint for explanation.
        in: query
        schema:
          type: integer
          enum:
          - 1
          - 2
          - 3
          default: 1
      - name: per_corpus
        description: Include per-corpus results.
        schema:
          type: boolean
          default: true
        in: query
      - name: combined
        description: Include combined results.
        schema:
          type: boolean
          default: true
        in: query
      - $ref: '#/components/parameters/IncrementalProgress'
      responses:
        '200':
          description: OK
          content:
            applicatoin/json:
              schema:
                type: object
                properties:
                  corpora:
                    type: object
                    description: An object with corpus names as keys and time statistics objects as values.
                    additionalProperties:
                      description: Number of tokens per time period.
                      type: object
                      additionalProperties:
                        type: integer
                    example:
                      ROMI:
                        2017: 15366
                        2018: 7437
                  combined:
                    type: object
                    description: Number of tokens per time period.
                    additionalProperties:
                      type: integer
                    example:
                      2017: 15366
                      2018: 7437
                  time:
                    $ref: '#/components/schemas/Time'
      security:
      - basicAuth: []
      operationId: getTimespan
      x-operation-id-source: derived
    servers:
    - url: https://ws.spraakbanken.gu.se/ws/korp/v8
  /lemgram_count:
    get:
      summary: Lemgram Statistics
      description: 'Return the number of occurrences of one or more lemgrams in one or more corpora.


        ### Example


        Get number of occurrences of the lemgrams `ge..vb.1` and `ta..vb.1` in a single corpus:

        `/lemgram_count?lemgram=ge..vb.1,ta..vb.1&corpus=ROMI`'
      tags:
      - Statistics
      parameters:
      - name: lemgram
        description: Lemgram to look up.
        schema:
          type: array
          items:
            type: string
        required: true
        in: query
        explode: false
      - name: corpus
        description: Corpus name. All corpora if omitted.
        schema:
          type: array
          items:
            type: string
        in: query
        explode: false
      - name: count
        description: 'What type of ocurrences to count. Available options are:


          * `lemgram` (default)

          * `prefix`

          * `suffix`

          '
        schema:
          type: string
          enum:
          - lemgram
          - prefix
          - suffix
          default: lemgram
        in: query
      - $ref: '#/components/parameters/IncrementalProgress'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Lemgrams as keys with absolute frequencies as values.
                properties:
                  time:
                    $ref: '#/components/schemas/Time'
                additionalProperties:
                  type: integer
                example:
                  cat..nn.1: 354
                  dog..nn.1: 85
      security:
      - basicAuth: []
      operationId: getLemgramCount
      x-operation-id-source: derived
    servers:
    - url: https://ws.spraakbanken.gu.se/ws/korp/v8
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    StatisticsDto:
      properties:
        value:
          anyOf:
          - type: string
          - {}
          title: Value
        count:
          type: integer
          title: Count
      type: object
      required:
      - value
      - count
      title: StatisticsDto
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Time:
      type: number
      description: Execution time in seconds.
      example: 0.0125
  parameters:
    DefaultWithin:
      name: default_within
      description: Prevent search from crossing boundaries of the given structural attribute, e.g. 'sentence'.
      in: query
      schema:
        type: string
        example: sentence
    IgnoreCase:
      name: ignore_case
      description: Change all values of the given attribute(s) to lowercase.
      in: query
      schema:
        type: array
        items:
          type: string
      example:
      - word
      - pos
      explode: false
    TimeTo:
      name: to
      description: Only include results contained by date range specified by `from` and `to`. Must be used together with `from`. On the format `YYYYMMDDhhmmss`.
      in: query
      schema:
        type: string
    TimeFrom:
      name: from
      description: Only include results contained by date range specified by `from` and `to`. Must be used together with `to`. On the format `YYYYMMDDhhmmss`.
      in: query
      schema:
        type: string
    GroupByStruct:
      name: group_by_struct
      description: Structural attribute by which the hits should be grouped. The value for the *first* token of the hit will be used.
      in: query
      schema:
        type: array
        items:
          type: string
      explode: false
      example:
      - text_author
      - text_title
    Granularity:
      name: granularity
      description: 'Time resolution. Available options are:

        * `y` - Year (default)

        * `m` - Month

        * `d` - Day

        * `h` - Hour

        * `n` - Minute

        * `s` - Second

        '
      in: query
      schema:
        type: string
        enum:
        - y
        - m
        - d
        - h
        - n
        - s
        default: y
    ExpandPrequeries:
      name: expand_prequeries
      description: When using multiple CQP queries (`cqp#`), this determines whether subsequent queries should be executed on the containing sentences (or any other structural attribute defined by `within`) from the previous query, or just the actual matched tokens. Enabled by default.
      in: query
      schema:
        type: boolean
        default: true
    Corpus:
      name: corpus
      description: Corpus name.
      in: query
      schema:
        type: array
        items:
          type: string
        example:
        - ROMI
        - SUC3
      explode: false
      required: true
    IncrementalProgress:
      name: incremental
      description: Incrementally return progress updates when the calculation for each corpus is finished.
      in: query
      schema:
        type: boolean
        default: false
    Within:
      name: within
      description: Like default_within, but for specific corpora, overriding the default. Specified using the format 'corpus:attribute'.
      in: query
      explode: false
      schema:
        type: array
        items:
          type: string
        example:
        - ROMI:paragraph
        - SUC3:text
    CQPn:
      name: cqp#
      description: 'Where # is a number, e.g. `cqp1`, `cqp2`. In addition to the `cqp` parameter, you can add additional CQP queries that will be executed on the result of the previous query (i.e. searching within search results). The final result returned to the user will be that of the last numbered query.'
      in: query
      schema:
        type: string
        example: '[pos="NN"]'
    CQP:
      name: cqp
      description: CQP query.
      in: query
      schema:
        type: string
      required: true
      example: '[word="flower"]'
    GroupBy:
      name: group_by
      description: Positional attribute by which the hits should be grouped. Defaults to `word` if neither `group_by` nor `group_by_struct` is defined.
      in: query
      schema:
        type: array
        items:
          type: string
      explode: false
      example:
      - pos
      - baseform
    SubCQPn:
      name: subcqp#
      description: 'Where # is a number. Sub-queries to the main query (or last **cqp#** query). Any number of numbered subcqp-parameters can be used. These will always be executed on just the actual matched tokens from the main query (i.e. no expansion), and the result for each subquery will be included as a separate object in the final JSON, in addition to the main query result.'
      in: query
      schema:
        type: string
  securitySchemes:
    APIKeyQuery:
      type: apiKey
      in: query
      name: api_key
    HTTPBearer:
      type: http
      scheme: bearer
    basicAuth:
      type: http
      scheme: basic
x-refined-from:
- university-of-gothenburg-karp-api-openapi.json
- university-of-gothenburg-korp-api-openapi.yml