Perform a simple query
Perform a simple query
Ultimately, the goal of any Coveo user is to perform queries against a unified, secured index in a specific Coveo organization, and retrieve the most relevant query result items.
Use the Search request to the Search API operation to perform a simple query:
Request template
POST https://<MyOrganizationId>.org.coveo.com/rest/search/v2?organizationId=<MyOrganizationId> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>
Payload
{
"q": <MyQuery>
}
In the query path:
- Replace
<MyOrganizationId>
with the actual ID of the target Coveo organization.
In the query string:
-
If the access token you’re using to authenticate the call doesn’t implicitly specify the organization it refers to (i.e., if it’s not a search token):
- Replace
<MyOrganizationId>
with the actual ID of the target Coveo organization.
Otherwise, you don’t need to include the
organizationId
parameter at al in the query string. - Replace
In the Authorization
HTTP header:
-
Replace
<MyAccessToken>
with an access token that grants the privilege to execute queries in the target Coveo organization (see Get your Coveo access token and Authentication methods).You can pass an access token as a query string argument (e.g.,
access_token=MyAccessToken
) rather than in anAuthorization
header.
In the request body:
-
Replace
<MyQuery>
with the basic query expression (q
) you want to forward to the Search API, such as the keywords an end user would enter in a search box.You can pass one or more keywords such as
human resources jobs
to get all source items containing these keywords.You can pass an empty request body rather than specifying a
q
value to return all items in the target organization index.You can include exact phrase match requests in the
q
value by surrounding groups of keywords with properly escaped double quote characters (e.g.,"q": "Coveo \"Cloud V2\" platform"
).Unless you explicitly set the
enableQuerySyntax
property tofalse
in the request body, you can also include any valid Coveo query syntax in theq
value (e.g.,"q": "Example AND @sourcetype==Web"
).
The body of a successful response (200 OK
) contains information about the query itself, such as its duration
and the totalCount
of query result items. Most importantly, the response body contains the query results
.
Sometimes, the response body also contains an executionReport
with detailed debug information.
By default, elements in the results
array are sorted by relevancy: a standard set of ranking rules is applied to compute a score
value for each query result item; the higher a query result item score
value is, the lower its 0-based index position in the results
array will be. There are several ways you can impact the score
value of query result items. Of course, the Search API also allows you to use other sort criteria than the score
value, so you should never have to sort query result items client-side.
Each element in the results
array contains specific information about a single query result item: its title
, clickUri
, automatically generated excerpt
, etc. You can leverage those values to display relevant information when rendering the query results in a graphical search interface. You can also take advantage of the titleHighlights
and excerptHighlights
properties to adequately emphasize basic query expression keywords in the title and excerpt.
The raw
property of each results
element is also very important, as it holds the fields which were retrieved for this item, and their corresponding values. Each field typically contains specific metadata about an item: its most recent modification date
, its size
, the name of its source
, its sourceType
, etc. You can explicitly specify which fields to include in (or exclude from) the query result items when performing a query.
Sample request
Request - Forwarding a basic query expression to the Search API
POST https://mycoveocloudv2organizationg8tp8wu3.org.coveo.com/rest/search/v2?organizationId=mycoveocloudv2organizationg8tp8wu3 HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
Payload
{
"q": "Example"
}
Successful response - 200 OK
{
"totalCount": 50,
...
"duration": 61,
...
"results": [
{
...
"title": "Example Domain",
...
"clickUri": "http://www.example.com/",
...
"excerpt": "Example Domain This domain is established to be used for illustrative examples in documents. ...",
...
"score": 4268,
...
"titleHighlights": [
{
"length": 7,
"offset": 0
}
],
...
"excerptHighlights": [
...
],
"raw": {
...
"date": 1376092475000,
"size": 1270,
"sourcetype": "Web",
"source": "My web source",
...
}
},
...
],
...
}