Performing a Query

You can perform a query by sending a GET or POST HTTP request to https://platform.cloud.coveo.com/rest/search/v2 (or https://cloudplatform.coveo.com/rest/search/v2 on Coveo Cloud V1). 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 (see Query Parameters).

  1. Performing a simple query using the GET method:

    GET https://platform.cloud.coveo.com/rest/search/v2?q=test HTTP/1.1
       
    Accept: application/json
    Authorization: Bearer **********-****-****-****-************
    
  2. Performing a simple query using the POST method:

    POST https://platform.cloud.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.

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://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
{
  "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,
  ...
}