Perform a query

This is for:

Developer

You can perform a query by sending a GET or POST HTTP request to:

The Search API query route supports several parameters which you can specify either in the query string, or in the JSON body of a POST request.

Examples

  1. Performing a query using the GET method:

    GET https://myorganizationid9sd8df7s.org.coveo.com/rest/search/v2?q=test HTTP/1.1
​
Accept: application/json
Authorization: Bearer **********-****-****-****-************

  2. Performing a query using the POST method:

    POST https://myorganizationid9sd8df7s.org.coveo.com/rest/search/v2 HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

    Payload

    {
  "q": "test"
}

Semantically, using the GET method to perform a query makes perfect sense. However, using the POST method is also legitimate, as a request body typically lends itself better to specifying complex parameters involving sub-objects (e.g., groupBy) than a query string does. For the sake of readability, this documentation uses the POST method in most examples and code samples.

Example

In a graphical search interface for an American bookstore, the end user has selected the Books tab and checked the Arthur Conan Doyle value in the Authors Facet. The end user now types adventure in the search box and submits a query. The resulting search request to the Search API looks like this:

POST https://myorganizationid9sd8df7s.org.coveo.com/rest/search/v2 HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "locale": "en-US",
  "searchHub": "BookstoreSearch",
  "tab": "Books",
  "cq": "@source==Books",
  "aq": "@author==\"Arthur Conan Doyle\"",
  "q": "adventure",
  "groupBy": [
    {
      "field": "@author",
      "sortCriteria": "AlphaAscending"
    },
    {
      "field": "@genre",
      "sortCriteria": "occurrences"
    }
  ]
}

200 OK response body (excerpt)

{
  ...
  "duration": 35,
  "groupByResults": [
    ...
  ],
  "indexDuration": 11,
  "requestDuration": 33,
  "results": [
    {
      "clickUri": "https://example.com/bookstore/books/authors/arthur-conan-doyle/adventures-of-sherlock-holmes",
      "excerpt": "The Adventures of Sherlock Holmes, a collection of 12 Sherlock Holmes tales ... written by Sir Arthur Conan Doyle and published in 1892 ...",
      "excerptHighlights": [
        {
          "length": 10,
          "offset": 4
        }
      ],
      "percentScore": 75.0698,
      "printableUri": "https://example.com/bookstore/books/authors/arthur-conan-doyle/adventures-of-sherlock-holmes",
      "printableUriHighlights": [
        {
          "length": 10,
          "offset": 63
        }
      ],
      "raw": {
        "date": 1532631456000,
        "author": "Arthur Conan Doyle",
        "documenttype": "Book",
        "filename": "adventures-of-sherlock-holmes.html",
        "filetype": "html",
        "indexeddate": 1532631456000,
        "language": [
          "English"
        ],
        "permantentid": "ecc3fac22085f2712c8cd2144f9d195593710963dc2202b5256f8a4f5f6",
        "size": 50683,
        "source": "Books",
        "sourcetype": "Push",
        "title": "The Adventures of Sherlock Holmes",
        ...
      },
      "score": 4904,
      "title": "The Adventures of Sherlock Holmes",
      "titleHighlights": [
        {
          "length": 10,
          "offset": 4
        }
      ],
      "uniqueId": "42.19751$https://example.com/bookstore/books/authors/arthur-conan-doyle/adventures-of-sherlock-holmes",
      "uri": "https://example.com/bookstore/books/authors/arthur-conan-doyle/adventures-of-sherlock-holmes"
    },
    ...
  ],
  "searchUid": "7beff9c1-98f3-401c-ac16-10b90a8b810f",
  "totalCount": 60,
  "totalCountFiltered": 60,
  ...
}