Dictanova Developer Portal

Empower your data with semantic analysis. Integrate new features of customer feedback analysis with the Dictanova API.

Get Started

Search documents

This endpoint is used to perform powerful searches through the documents of a dataset. Search has many options that can be combined to allow you to find exactly what you need.

Check out API Reference for this endpoint.

Request

Query parameters

Parameter
Decsription

sortBy

Date field to use for sorting (example : sortBy=metadata.MY_DATE)

sortOrder

Sort order if sortBy is provided. Value can be DESC or ASC (example : sortOrder=ASC)

q

This parameter is used as a full text criterion. The request will target only terms matching this text (example : q=product)

When this parameter is used, TERMS criteria in the request body are ignored (query field)

This parameter works only with a minimum of 2 characters (except for Chinese where 1 character is enough)

Body

This sample request search for all documents with type set as PRODUCT_REVIEW. See the following section for full explanation on how to create a request.

curl -X POST \
 /search/datasets/DATASET_ID/documents \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "operator": "EQ",
  "field": "type",
  "value": "PRODUCT_REVIEW"
}'

Reply

The reply is a paginated list of documents.

Build a request

Operators

Search request can combine operators listed below.

Operator
Description

AND

boolean and

OR

boolean or

GT

greater than

LT

lower than

GTE

greater than or equal

LTE

lower than or equal

EQ

equal

NEQ

not equal

IN

in list of values

NIN

not in list of values

Fields

Search can target every field of the document using the following syntax.

Field
Description

createdAt

Creation date of document

Operators : GT, LT, GTE, LTE

updatedAt

Last update date of document

Operators : GT, LT, GTE, LTE

externalId

Unique identifier

Operators : EQ, NEQ, IN, NIN

type

Type of document in predefined list

Operators : EQ, NEQ, IN, NIN

lang

Lang of document in list supported by Dictanova API

Operators : EQ, NEQ, IN, NIN

TERMS

List of terms contained in document (enriched by Dictanova Engine)

Operators : EQ, NEQ, IN, NIN

TOPICS

List of topics matching document (enriched by Dictanova Engine)

Operators : EQ, NEQ, IN, NIN

IMPORT

Unique identifier of import

Operators : EQ, NEQ, IN, NIN

metadata.MTD_CODE

Metadata defined by code MTD_CODE in the dataset model.

Operators :

  • Datetime : GT, LT, GTE, LTE
  • Number : GT, LT, GTE, LTE
  • NPS : GT, LT, GTE, LTE
  • CSAT : GT, LT, GTE, LTE
  • CES : GT, LT, GTE, LTE
  • String : EQ, NEQ, IN, NIN
  • LatLng : EQ, IN

Single criterion request

To build a request with a single criterion, simply target the field and set the value. This sample shows how to target all documents of type PRODUCT_REVIEW.

{
  "operator": "EQ",
  "field": "type",
  "value": "PRODUCT_REVIEW"
}

Multiple criteria request

To combine criteria, you have to use AND or OR operators. This sample shows how to target documents of type PRODUCT_REVIEW and for which the language field (lang) is other than French (fr).

{
  "operator" : "AND",
  "criteria" : [
    {
      "operator": "EQ",
      "field": "type",
      "value": "PRODUCT_REVIEW"
    },
    {
      "operator": "NEQ",
      "field": "lang",
      "value": "fr"
    }
  ]
}

Operators AND and OR can be combined and embedded. This sample shows how to target documents of type PRODUCT_REVIEW and language (lang) set as English (en) or Chinese (zh).

{
  "operator" : "AND",
  "criteria" : [
    {
      "operator": "EQ",
      "field": "type",
      "value": "PRODUCT_REVIEW"
    },
    {
      "operator": "OR",
      "criteria" : [
        {
          "operator": "EQ",
          "field": "lang",
          "value": "en"
        },
        {
          "operator": "EQ",
          "field": "lang",
          "value": "zh"
        }
      ]
    }
  ]
}

Add semantic criterias

To target terms extracted from the document by Dictanova Engine, you have to use the TERMS field with termIds. This specific field can be associated with an opinion (POSITIVE, NEUTRAL or NEGATIVE). To find termIds, please use the search terms endpoint.

Read Build a semantic search engine to learn how to use this feature.

{
  "operator": "EQ",
  "field": "TERMS",
  "value": "package__NOUN__0",
  "opinion" : "POSITIVE"
}

Add topics criterias

To target topics matching the document, you have to use the TOPICS field with topicIds. This specific field can be associated with an opinion (POSITIVE, NEUTRAL or NEGATIVE). To find topicIds, please use the get topics endpoint.

{
  "operator": "EQ",
  "field": "TOPICS",
  "value": "5b9a70d8e2812d063d509fc2",
  "opinion" : "POSITIVE"
}

Sample with all kinds of fields and operators

This sample do not show anything functional but illustrates the usage of operators and fields.

{
  "operator": "AND",
  "criteria": [
    // target documents created in 2017
    {
      "operator" : "AND",
      "criteria" : [
        {
          "operator": "GTE",
          "field": "createdAt",
          "value": "2017-01-01T00:00:00Z"
        },
        {
          "operator": "LTE",
          "field": "createdAt",
          "value": "2017-12-31T00:00:00Z"
        }
      ]
    },
    // target documents with type IN given types
    {
      "operator": "IN",
      "field": "type",
      "value": ["PRODUCT_REVIEW", "NO_TYPE"]
    },
    // target documents around this point
    {
      "operator": "EQ",
      "field": "metadata.position",
      "value": "47.207738,-1.536706"
    },
    // target documents not in these stores
    {
      "operator": "NIN",
      "field": "metadata.store",
      "value": ["Paris", "Lyon", "Marseille"]
    },
    // target only promoters
    {
      "operator" : "AND",
      "criteria" : [
        {
          "operator": "GTE",
          "field": "metadata.my_nps",
          "value": 9
        },
        {
          "operator": "LTE",
          "field": "metadata.my_nps",
          "value": 10
        }
      ]
    }
  ]
}