Question GET list

GET /questions

Returns a list of published questions. By default, all published questions are returned, ordered by their last activity (descending). A combination of filters, search queries and ordering criteria can be applied to the list, as documented below.

When a query parameter is provided, only questions that match the given query are returned. If no sort parameter is specified, then the questions that are most relevant for the given query are returned first. If sort is specified, then the output will be sorted according to the specified sort criteria (which might deliver less meaningful results first). Consult the Concepts section for more technical details about search.

Response

If a query is specified in the request, then every item in the response will have an additional field search_metadata. The search_metadata object contains:

• score
• is_relevant if the item is determined to be significantly relevant to the user query
• highlighting object if highlighting can be applied

Score

The score of a question is a positive floating-point value that expresses how well the question fits the given search query, with better matches having a higher score. If no other sort parameter is specified in the request, then the results will be sorted by this score in descending order.

The scores of the results of any query are always roughly centred around 1.0. Questions that contain the search query in their title will generally score clearly higher than 1.0. Question where the search query is only found in some comment or attachment will generally score clearly lower than 1.0. As such, a value around 1.0 could be useful as a threshold to keep only highly relevant search results.

Highlighting

The highlighting object of a question is defined by the properties query_field, id, fragment, start, and end, which correspond to the element of the question that best matches the provided search query. If no highlighting can be applied to a question, then the question will not have a highlighting object. The query_field is the field name of the highlighted element, which is one of those included in the query_fields parameter or any of them if the parameter is not specified in the query. The relation between query_field and id is defined as follows:

The property fragment contains a fragment of the text, in which the matched words from the search query are surrounded by <em> tags. Apart from the <em> tags, the highlighted fragment is HTML encoded, so this string can be used without risk of HTML injections. If the best matching query_field is the title, then the fragment always contains the entire title.

The properties start and end are boolean values that define the position of the fragment in the full text. start is true for those fragments that start at the beginning of the text, and end is true for those that end at the end of the text. Additionally, this means that if start and end are both true, then the whole fragment covers the full text, and if startand end are both false, then the fragment is in the middle. These values may be used to decide whether to add an ellipsis (...) in front of and/or after the fragment when displaying the fragment to the user.

Logging

If the parameter log_query_type is not defined, the response will not contain search_query_id.

If the parameter log_query_type is defined and offset == 0 and query is defined:

• The query will be logged.
• The response will include a non-null integer search_query_id.

Warning: Logging should only be enabled when the query and the ensuing clicks may be used for learning about the user's interest and for optimising the ranking of results on future search queries. It is advised that integrations don’t use this parameter and (if required) implement their own logging instead.

{
  "search_query_id": 123,
  "total": 1,
  "_links": {
    "self": {
      "href": "/api/v1/questions?tags=sherlock&query=holmes&offset=0&limit=10&log_query_type=manual"
    }
  },
  "items": [
    {
      "description": null,
      "solution_count": 1,
      "slug": "is-there-a-study-in-scarlet",
      "id": 21,
      "updated": "2015-02-02T11:36:05.000Z",
      "content_updated": "2015-02-02T11:36:05.000Z",
      "last_activity": "2015-02-02T11:41:08.000Z",
      "image": "https://cdn.example.com/avatar/default/2d/1b84215e2f035a22f6fec213d3b1d9.jpg",
      "language": "en",
      "tag_relations": [
        {
          "tag": "Study",
          "is_auto": true
        }
      ],
      "title": "Is there a Study in Scarlet?",
      "attachments": "/questions/21/attachments",
      "is_published": true,
      "published": "2015-02-02T11:36:05.000Z",
      "created": "2015-02-02T11:31:05.000Z",
      "is_deleted": false,
      "view_count": 28,
      "search_metadata": {
        "highlighting": {
          "query_field": "solutions",
          "fragment": "Dr Watson, Sherlock <em>Holmes</em> partner Astrid Farnsworth",
          "id": 1092,
          "start": true,
          "end": false
        },
        "score": 5.8311359538639,
        "is_relevant": true
      },
      "upvote_count": 23,
      "translations": [
        {
          "language": "fr",
          "title": "Y a-t-il une étude à Scarlet?",
          "description": null
        }
      ]
    }
  ]
}