The Search Event API #
The search event API allows you to insert bulk search event data to Releva. Any insert submitted through this API will be live within 10 seconds of receiving a successful response.
Do I need to call it? #
Yes, if you want to update user profile data with search events from your back end. If you want to send search events from the front-end read our front end integration page.
Request Parameters #
For example, a client just performed a search for computers by adding filters for brand, RAM, processor, gpu, etc. You may track this search by sending a search event to the API using the following curl equivalent:
curl -H 'Content-Type: application/json' -H 'Authorization: Bearer <secretKey>' -XPOST https://releva.ai/api/v0/search -d'
{
"events": [
{
"locale": "bg",
"products": [
{ "id": "4522211" },
{ "id": "4521245" },
{ "id": "4524221" }
],
"filter": {
"operator": "and",
"nested": [
{
"key": "custom.string.estate_type",
"operator": "eq",
"action": "include",
"value": "Тристаен апартамент"
},
{
"operator": "or",
"nested": [
{
"key": "custom.string.quarter",
"operator": "eq",
"action": "include",
"value": "Младост 1"
},
{
"key": "custom.string.quarter",
"operator": "eq",
"action": "include",
"value": "Мусагеница"
}
]
},
{
"key": "price",
"operator": "gte",
"action": "include",
"value": "100000"
},
{
"key": "price",
"operator": "lte",
"action": "include",
"value": "176400"
},
{
"key": "custom.numeric.square",
"operator": "gte",
"action": "include",
"value": "78"
}
]
},
"custom": {
"string": [
{
"key": "agent",
"values": [
"manual"
]
},
{
"values": [
"John Doe"
],
"key": "name"
},
{
"values": [
"+123456789"
],
"key": "phone"
}
]
},
"tags": ["view"],
"email": "georgi@releva.ai"
}
]
}'The events array #
This is an array of events with the following properties:
| Field | Type | Description |
|---|---|---|
| String | The email of the user that has performed this action. | |
| locale | String (Optional) | If you support multiple languages or currencies, set this to the current locale. |
| filter | Object (Optional) | The filter that has been used during this search. If the user performed a full-text search model this is part of the constraints fields. |
| products | Array (Optional) | Product identifiers associated with this event. |
| timestamp | ISO-8601 String (Optional) | The date and time when this event happened. |
| custom | Object (Optional) | The custom fields are associated with the event. |
| tags | Array[String] (Optional) | The tags associated with this event. |
The filter object #
This is an object with the following properties:
| Field | Type | Description |
|---|---|---|
| operator | String | It has two values: – “or” – used when we want only one condition from the sibling “nested” array to be true in order to return products – “and” – used when we want every condition from the sibling “nested” array to be true in order to return products |
| nested | Array | It contains all of the conditions you can check the conditions in the below table for context.nested. Also, you can nest inner conditions with a different “operator” if you append an object inside this array with the same fields “operator” and “nested” |
The filter.nested array #
This is an array of conditions used for the search with the following properties:
| Field | Type | Description |
|---|---|---|
| key | String | Option one you can use default fields like ‘price’. Option two you can use the custom fields in the product like this -> custom.[type].[key], for example, custom.string.estate_type. (Custom fields have three types – “string”, “numeric” and “date”) |
| operator | String | What operator do you want to use to check the value given in the “value” field with the value from the products by the key given above. We support these operators: – eq – Equal to – lt – Less than – gt – Greater than – lte – Less than or equal to – gte – Greater than or equal to |
| action | String | What action do you want to perform if the value checked with the operator has found products by the given key.We support these actions: – include – Include only the products that match the condition – exclude – Exclude only the products that match the condition – bury – Will make the products appear at the bottom of the search if they match the condition – boost – Will make the products appear at the top of the search if they match the condition |
| value | String | The value that you want to be checked in the products by the operator and key |
| weight | Integer (Optional) | Weight is used only if you choose boost or bury in the action field and if you have more than one “boost” or “burry”, they will be ordered by the given weight. |
Response Format #
A successful response will return HTTP Status 202 with an empty response body ({}).
An error response will return a HTTP 4xx or 5xx status code and have the following structure:
{
"message": "A description of the error and how to fix it, if it's a client error."
}