API v2

The API can be accessed at /api/v2 and supports JSON and XML as output format. The XML is generated from the JSON using the bijective XPath 3.1 transformation json-to-xml. If an end point also supports HTML output, the HTML is generated from the XML using the same XSLT transformations as in the main web search interface.

Contents

• Common parameters for all end points
• Get arguments
• Get argument
• Get aspect space
• Get pro/con counts

Common parameters for all end points

• format=quality-values-list The output format the response should have in a preference-ordered list using quality values syntax. Can also be specified using the Accept HTTP header (but this parameter takes precedence). Also allows for specifying just the second part of the MIME type, e.g.: json, in which case a */ is pre-pended automatically. The default is json.
• locale=quality-values-list The locale the response should have in a preference-ordered list using quality values syntax Can also be specified using the Accept-Language HTTP header (but this parameter takes precedence). Only relevant for HTML output. Only en (English) is supported at the moment, which is also the default.
• fields=names-list The fields/attributes of the result list to show, separated by commata (,). If set, all other fields will not be sent back to the client, which can considerably reduce the message size. Only available for JSON and XML output.
  arguments?query=art&fields=arguments.id,arguments.context.aspects&format=json

Get arguments

GET /api/v2/arguments Uses the same parameters as the usual args.me search.html: for example, /search.html?query=art&pageLayout=pro-con corresponds to /api/v2/arguments?query=art&pageLayout=pro-con. Supports JSON, XML, and HTML as output format.

• query=text Specifies the query for which arguments should be retrieved. Use double quotes ("") for phrase queries and plus signs (+) between words to form multiple-word queries.
  arguments?query=art&format=json
• aspectRanks=criteria Restricts the retrieved arguments to those that fulfill all of given comma-separated aspect rank critera. An aspect rank criterium is one of
  • A single aspect rank predicate: either aspect, aspect < rank, or aspect <= rank, where aspect is the name of the aspect whose rank should be tested, and rank is the rank value (starting with 1 for top-ranked) to test against. If only the name of the aspect is given, it is just tested whether the argument has the aspect at all. In all cases a rank predicate requires the argument to have the respective aspect.
  • A conjunction: ALL(criteria), where criteria is a list of comma-separated aspect rank criteria where the argument has to fulfill all of them to fulfill the conjunction.
  • A disjunction: ANY(criteria), where criteria is a list of comma-separated aspect rank criteria where the argument has to fulfill at least one of them to fulfill the disjunction.
  Other aspects can be ignored for the rank computation using ignoredAspects. Those ignored aspects will be treated as if the argument would not have that aspect for the matter of fulfilling aspect rank criteria.
  arguments?query=art&aspectRanks=ANY(Copyright<=1)&format=json
• aspectSpace=parameters Specifies the parameters that are used to retrieve the arguments from which the aspect space is created. The parameters have to be URI component encoded (in addition to the usual encoding for get parameters: the same encoding function has to be applied here). Example: "query%3Drights%26mode%3Dall" (which decodes to "query=rights&mode=all"). The specified aspect space is used by aspectSpacePolygon to determine the Cartesian coordinates of arguments. Also, specifying this parameter will add coordinates of each retrieved argument in the aspect space to the argument's context attributes.
  arguments?query=art&aspectSpace=query%3Dart%26mode$3Dall&format=json
• aspectSpacePolygon=polygon Restricts the retrieved arguments to those that fall inside the given polygon for some aspect space, where polygon is a space-separated list of the coordinates (x,y, where both x and y are in the interval [-1;1]) of the polygon's points in the Cartesian coordinate system that corresponds to the barycentric aspect space. This parameter requires to specify the aspect space using aspectSpace.
  arguments?query=art&aspectSpace=query%3Dart%26mode$3Dall&aspectSpacePolygon=0,0 0.5,0 0.5,0.5 0,0.5&format=json
• corpora=name Restricts the retrieved arguments to those that are part of a corpus in the given comma-separated list. Note that, in a few cases, arguments of the corpus may no longer be retrievable (filtered out for various reasons) or be changed (e.g., cleaned of formatting and boilerplate texts like "thank you for this discussion"). Moreover, since we frequently extend (and sometimes change) the context attributes, the JSON of the arguments will likely be different from that of the corpus. Available values: args-me-2020-04-01.
  arguments?query=art&corpora=args-me-2020-04-01&format=json
• ids=id-list Restricts the retrieved arguments to those with IDs in the given comma-separated list.
  arguments?query=art&ids=Se13b1d03-Acf23c508,Se13b1d03-A695f13fd&format=json
• ignoredAspects=aspects Specifies aspects to ignore when restricting the retrieved arguments by aspectRanks.
  arguments?query=art&aspectRanks=ANY(Copyright<%3D1)&ignoredAspects=Censorship,Pornography&format=json
• mode=name Restricts the retrieved arguments to those with the given mode. Available values: all, discussion, person.
  arguments?query=rights&mode=person&format=json
• page=number Specifies the page of the result list to show (starting with 1). If both this and pageOffset are specified, page takes precedence. The number of arguments on the page can be specified through pageSize. Default: 1 (first page).
  arguments?query=art&page=2&format=json
• pageLayout=name Specifies the layout of the result page (called view in the graphical user interface). Currently supported values are pro-con and one-column (the default).
  arguments?query=art&pageLayout=pro-con&format=json
• pageOffset=offset Specifies the index in the result list of the first argument to show (starting with 0). If both this an page are specified, page takes precedence. The number of arguments on the page can be specified through pageSize. Default: 0 (first argument).
  arguments?query=art&pageOffset=1&format=json
• pageSize=size Specifies the number of arguments the response can contain. The page offset can be specified through page or directly through pageSize. Default: 10; Minimum: 1; Maximum: 1000.
  arguments?query=art&page=2&format=json
• sourceDomain=name Restricts the retrieved arguments to those that stem form a domain in the given comma-separated list. Available values: canadian-parliament, debatepedia, debatewise, debate.org, idebate.
  arguments?query=art&sourceDomain=idebate,debatepedia&format=json

Response

{
  "query": {
    "text":"text",
    "properties":{
      "key":"value", ...
    },
    "start":"timestamp"
  },
  "arguments":[
    {
      "id":"id",
      "conclusion":"text",
      "premises":[
        {
          "text":"text",
          "stance":"stance-towards-conclusion: PRO or CON",
          "annotations":[
            {
              "type":"java-class",
              "start":"character-offset",
              "end":"character-offset",
              "source":"java-class, url, or other identifier"
            }, ...
          ]
        }, ...
      ],
      "context":{
        "key":"value", ...
      },
      "summary":"text",
      "explanation":{
        "score":score,
        "name":score-name,
        "details":[
          { explanation }, ...
        ]
      },
      "stance":"stance-towards-query: PRO or CON"
    }, ...
  ],
  "totalSize":number-of-matching-arguments-in-index,
  "resultsBefore":number-of-arguments-on-previous-pages,
  "retrievalTimeInMilliseconds":milliseconds-between-query-parsing-and-result-presentation
}

Get argument

GET /api/v2/arguments/id

This end point offers no additional parameters. Supports JSON and XML as output format.

Response

{
  "id":"id",
  "conclusion":"text",
  "premises":[
    {
      "text":"text",
      "stance":"stance-towards-conclusion: PRO or CON",
      "annotations":[
        {
          "type":"java-class",
          "start":"character-offset",
          "end":"character-offset"
        }, ...
      ]
    }, ...
  ],
  "context":{
    "key":"value", ...
  }
}

Get aspect space

GET /api/v2/aspectSpace

The same parameters as for GET /api/v2/arguments apply. The aspect space is created from the arguments that are retrieved using these parameters. In addition, the following parameters are available to modify the way the aspect space is created. Supports JSON and XML as output format.

• ignoreQueryTermDimensions=boolean Specifies whether to ignore all aspects that are also query terms. This setting avoids to have an aspect that naturally every argument has. Default: true.
  aspectSpace?query=abortion&ignoreQueryTermDimensions=false&format=json
• mergeToOther=boolean Specifies that, if more than numDimensions aspects are found in the retrieved arguments, the first numDimensions - 1 aspects are represented as an dimension each, whereas all others are represented by a single dimension (the last one). If the value of this parameter is false, instead the first numDimensions aspects are represented as an dimension each and all others are discarded. Default: true.
  aspectSpace?query=abortion&mergeToOther=false&format=json
• numDimensions=amount Specifies the number of dimensions the created aspect space will have at most. If more aspects than the specified number of dimensions are found in the retrieved arguments, mergeToOther specifies how this situation is handled.
  aspectSpace?query=abortion&numDimensions=3&format=json

Response

{
  "dimensions":[
    {
      "aspects":["name", ...],
      "weight":normalized-sum-of-weights-from-arguments,
      "index":non-negative-integer,
      "cartesianX":X-coordinate-of-this-dimension-in-an-cartesian-system in [-1;1],
      "cartesianY":Y-coordinate-of-this-dimension-in-an-cartesian-system in [-1;1]
    }, ...
  ],
  "ignoredAspects":[ "aspects-ignored-due-to-query-terms", ... ]
}

Get pro/con counts

GET /api/v2/counts Uses the same parameters as get arguments. Supports JSON and XML as output format.

Response

{
  "byFilter":{
    "context-key1":{
      "context-value1":{
        "pro":"amount",
        "con":"amount",
      }, ...
    }, ...
  },
  "total":{
    "pro":"amount",
    "con":"amount",
  }
}

Back to main page