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