Tags


For a general introduction on tagging, go to the overview of all tagging endpoints.

Search

GET /search/tags
Parameter Type Default Required Description
query string - Tag label to search by.
exclude string - Specify one or more tags which should be excluded from the search.
used_only boolean false Deprecated. Specify whether only tags which are used in at least one question should be included. This flag should not be used, because tags that are only connected to solutions or used otherwise, are ignored.
limit int 10 Sets how many tags are returned at once.
offset int 0 Offset from the first tag.

Text search on all tags.

{
    "total": 1,
    "_links": {
        "self": {
            "href": "/search/tags?query=Sherlock"
        }
    },
    "items": [
        "Sherlock",
        ...
    ]
}

Tag Suggestions

POST /search/tags/suggestions

This request tries to find tags that fit well with the provided title and description texts. The title text is weighted stronger than the description text.

This endpoint is optimised to obtain good tags for questions, helping the expert search to identify the best experts when the question is published. For obtaining tags for other input types, look at the overview of all tagging endpoints.

The response may contain both tags that already exist in the network, as well as new tags that are extracted from the given text.

The response contains an ordered list of tags, with the most relevant tags at the start of the list.

It is also possible to obtain a weight for every tag in the response by using the POST /search/tags/weighted-suggestions endpoint documented below.

Parameter Type Default Required Description
title string - Title text.
description string (HTML + mentioning markup) - Description text.
texts Array of JSONs with field text (string), factor (double) and text-format [] List of texts to suggest tags from with their weights multiplied by a given factor. Factor is optional, if not stated it is 1.0
excluded_tags array of strings [] A list of tags that are excluded from the search.
limit int 10 The maximum number of tags that are returned.
text_processing string of text processing type "default" The tag behaviour used for tagging
strict_error_handling boolean true This parameter decides what happens when failures occur during tagging. With strict error handling, the request will fail if any problems occur. With non-strict error handling, the endpoint will try to ignore any errors and still return tags, though the quality of these tags cannot be guaranteed.

Json Payload

{
    "title": "Is Sherlock Holmes really dead?",
    "description": "<p>Post any information to 221B Baker Street, London.</p>",
    "texts": [
      {
        "text": "I am excited for 2020 Olympics", 
        "factor": 2.0,
        "text_format": "plain"
      }
    ],
    "excluded_tags": ["Holmes"],
    "limit": 3
}

Response

{
    "total": 3,
    "items": [
        "Sherlock",
        "London",
        "Olympics"
    ]
}

Tag suggestions with weights

There is also an endpoint available for returning weight of the tags along with their label. The higher the weight, the more important the corresponding tag for the given title and description.

POST /search/tags/weighted-suggestions

This endpoint works the same as POST /search/tags/suggestions (documented above) except that the response format is extended.

Response

{
    "total": 3,
    "items": [
        {
          "label": "Olympics",
          "weight": 2.1343729437
        },
        {
          "label": "Sherlock",
          "weight": 1.4178433289
        },
        {
          "label": "London",
          "weight": 1.1327843279
        }
    ]
}