1. Examples of basic search and recommendation use cases

Querying content

Use the following objects to query content:

  • query - specifies the string for each type of query.

  • content - specifies the content type that the query applies to. The default content type is product.

To specify the total number of items per page in the response, use the optional key, n_item.

The following sections show some examples of basic content queries. See advanced use cases for more examples.

Querying product content

The following code shows a request to query product content type. You want three product results (n_item = 3) and use the keyphrase red.

{
  "query": {
    "keyphrase": ["red"]
  },
  "n_item": 3,
  "content": {}
}
Note

If you do not define any content type, Discover uses the default value.

The following code shows the corresponding response:

{
  "ts": 1480977544,
  "rid": "response_id_q1",
  "url": "/searchpage?keyphrase=red",
  "query2id": {
    "keyphrase": "keyphrase_id_red"
  },
  "content": {
    "product": {
      "value": [
        {"name": "shorts", "color": "red", "price": 25, 
         "image_url": "", "rating": 5 },
        {"name": "red hat", "price": 10, "rating": 1},
        {"name": "pants", "price": 50, "category_name": ["red"] }
      ]
    }
  },
  "n_item": 3,
  "total_item": 5,
  "page_number": 1,
  "total_page": 2
}

The response returns any product that contains red in any attribute.

In the example, there are two pages of results. You can query the next pages as shown in Retrieving a specific page of the search results.

Each response returns a default set of attributes for an item. For simplicity in this example, we only use a few attributes. You can get a different subset of attributes in the response as shown in Getting a subset of content value attributes.

Querying with an incomplete keyphrase

The following code shows a request with a query that uses an incomplete keyphrase, shor.

Note

If the query keyphrase gives no results, Discover looks for results that match a suggested keyphrase. You must include a suggestion parameter in your request to get results for a suggested keyphrase. You can also use a request_for parameter in your request to return your query.

{
  "query": {
    "keyphrase": ["shor"]
  },
  "content": {},
  "n_item": 2,
  "suggestion": {
    "keyphrase": {
      "max": 1
    }
  },
  "request_for": ["query"]
}

The following code shows the corresponding response:

{
  "ts": 1480977544,
  "rid": "response_id_q2",
  "url": "/searchpage?keyphrase=shorts",
  "query2id": {
    "keyphrase": "keyphrase_id_shorts"
  },
  "suggestion": {
        "keyphrase": [
            {
                "text": "short",
                "in_content": "product",
                "id": "suggestion_idc2hvcnQ="
            }
        ]
    },
  "content": {
    "product": {
      "value": [
        {"name": "swim short", "price": 25, "image_url": "", "rating": 5 },
        {"name": "casual short", "price": 10, "rating": 1}
      ]
    }
  },
  "request_for": {
    "query": {
      "keyphrase": "short",
      "orig_keyphrase": "shor"
    },
    "content": {},
    "n_item": 2
  },
  "n_item": 2,
  "total_item": 32,
  "page_number": 1,
  "total_page": 16
}

Recommendation for one widget

The following code shows a request for a recommendation for one widget. You select the widget with rfkid equal to rfkid_1.

{
  "widget": {
    "rfkid": "rfkid_1"
  },
  "content": {"product": {}},  
  "n_item": 2
}

The following code shows the corresponding response:

{
  "ts": 1480977544,
  "rid": "response_id_q2",
  "content": {
    "product": {
      "value": [
        {"name": "Opaque earrings", "id": "1024"},
        {"name": "Hanging earrings", "id": "1023"}
      ]
    }
  },
  "widget": {
    "rfkid": "rfkid_1"
  },
  "n_item": 2,
  "total_item": 2,
  "page_number": 1,
  "total_page": 1
}

Recommendation for two widgets

The following code shows a request for a recommendation for two widgets. You specify two rfkids: rfkid_1 and rfkid_2. The request overrides the first widget in the batch object.

{
   "batch": [
       {
         "widget": {"rfkid": "rfkid_1"}
       },
       {
         "widget": {"rfkid": "rfkid_2"}
       }
   ],
  "content": {"product": {}},
  "n_item": 2
}

The following code shows the corresponding response:

{
  "ts": 1480977544,
  "rid": "response_id_q2",
  "batch": [
        {
          "content": {
             "product": {
                "value": [
                     {"name": "Opaque earrings", "id": "1024"},
                     {"name": "Hanging earrings", "id": "1023"}
                ]
             }
          },
          "widget": {"rfkid": "rfkid_1"}
       }, 
       {
         "content": {
            "product": {
               "value": [
                    {"name": "Opaque necklace", "id": "1022"},
                    {"name": "Hanging necklace", "id": "1021"}
               ]
            }
         },
         "widget": {"rfkid": "rfkid_2"}
      }
  ]
  "n_item": 2,
  "total_item": 2,
  "page_number": 1,
  "total_page": 1
}

Recommendation with a product context widget

The following code shows a request for a recommendation with a product context widget.

{
  "widget": {
    "rfkid": "rfkid_2" 
  },
  "context": {"page": {"sku": ["sku1", "sku2"]}},
  "content": {"product": {}},  
  "n_item": 2
}

The following code shows the corresponding response:

{
  "ts": 1480977544,
  "rid": "response_id_q2",
  "widget_title": "Your title here",
  "widget": {
    "rfkid": "rfkid_2" 
  },
  "content": {
    "product": {
      "value": [
        {"name": "Opaque earrings", "id": "1024"},
        {"name": "Hanging earrings", "id": "1023"}
      ]
    }
  },
  "n_item": 2,
  "total_item": 2,
  "page_number": 1,
  "total_page": 1
}

Getting all possible product fields

The following code shows a request for all possible product fields using the get_fields flag within content.

{
    "content": {"product": {"get_fields": true}},  
    "n_item": 0
}

The following code shows the corresponding response:

{
  "ts": 1480977544,
  "rid": "response_id_712370513",
  "content": {
    "product": {
      "fields": [
        "name",
        "price",
        "image_url",
        "rating",
        "shoe_size"
      ]
    }
  },
  "n_item": 0,
  "total_item": 5,
  "page_number": 1,
  "total_page": 5
}
If you have suggestions for improving this article, let us know!