Perform a query

This is for:

Developer
In this article

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.

Query 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"
}

GET vs. POST

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

Detailed query example using POST

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

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,
  ...
}