Smart Search API

Service Description¶

This API endpoint can be used to query a universe with a complex set of filters.

The Insight API endpoint for the smart search is accessed through the following endpoint:

Smart Search

Below, we elaborate further on how to use this endpoint in practice.

Smart Search POST¶

The endpoint has a range of predefined fields to query data for. Let us look at an example.

Curl RequestHTTP Request

curl -X "POST" \
"https://api.data.investsuite.com/smart-search/" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "X-TENANT-ID: $TENANT_ID" \
-H "X-Api-Key: $IVS_API_SECRET" \
-d '{
    "query": {
        "xray": "$VALUE_STARS >= 5 & $STABILITY_STARS >= 5 & $PROFITABILITY_STARS >= 5"
    },
    "sorting_variables": {"xray": ["VALUE"], "sorting_order": ["VALUE"]},
    "xray_parameters": {
        "normalization_universe": "GLOBAL",
        "instrument_universe": "GLOBAL",
        "group_split_type": "REGION_SECTOR"
    }
}'

POST /smart-search/ HTTP/1.1
Host: api.data.investsuite.com
X-TENANT-ID: $TENANT_ID
X-Api-Key: $IVS_API_SECRET
accept: application/json
Content-Type: application/json

{
    "query": {
        "xray": "$VALUE_STARS >= 5 & $STABILITY_STARS >= 5 & $PROFITABILITY_STARS >= 5"
    },
    "sorting_variables": {"xray": ["VALUE"], "sorting_order": ["VALUE"]},
    "xray_parameters": {
        "normalization_universe": "GLOBAL",
        "instrument_universe": "GLOBAL",
        "group_split_type": "REGION_SECTOR"
    }
}

Field	Description	Data type	Example	Required
`query`	A dictionary containing the filters by filter type.	`dict`	{"xray": "$VALUE_STARS >= 5}	yes
`sorting_variables`	The sorting logic of the output payload.	`dict`	{"xray": ["VALUE"], "sorting_order": ["VALUE"]}	no
`group_split_type`	The type of grouping to use for ranking the variables. Possibilities are `REGION`, `SECTOR`, `REGION_SECTOR`, `SIZE`, `REGION_SIZE`, `SECTOR_SIZE` and `REGION_SECTOR_SIZE`.	`str`	"REGION_SECTOR"	no

The query dictionary is constructed as follows.

Field	Description	Data type	Example	Required
`reference`	A query on our reference data.	`str`	"$ANALYST_WEIGHTED_RECOMMENDATION <= 2.5"	no
`xray`	A query on our X-Ray data.	`str`	"$VALUE_STARS >= 5"	no
`derived`	A query on our derived data. Currenly only ANALYST_UPWARD_POTENTIAL is available.	`str`	"$ANALYST_UPWARD_POTENTIAL > 0"	no

The sorting dictionary is constructed as follows.

Field	Description	Data type	Example	Required
`reference`	The referene fields to sort on.	`list`	["ANALYST_WEIGHTED_RECOMMENDATION"]	no
`xray`	The X-Ray fields to sort on.	`list`	["VALUE"]	no
`derived`	The derived fields to sort on.	`list`	["ANALYST_UPWARD_POTENTIAL"]	no
`sorting_order`	The sorting order.	`list`	["VALUE", "ANALYST_UPWARD_POTENTIAL", "ANALYST_WEIGHTED_RECOMMENDATION"]	yes
`ascending`	Whether to sort ascending or descending.	`bool`	true	no

The X-Ray parameter dictionary is constructed as follows.

Field	Description	Data type	Example	Required
`normalization_universe`	The universe over wich the scores are normalized.	`str`	"GLOBAL"	no
`instrument_universe`	The universe for wich the scores are returned.	`str`	"GLOBAL"	no
`group_split_type`	The type of grouping to use for ranking the variables. Possibilities are `REGION`, `SECTOR`, `REGION_SECTOR`, `SIZE`, `REGION_SIZE`, `SECTOR_SIZE` and `REGION_SECTOR_SIZE`.	`str`	"REGION_SECTOR"	no

After uploading data, we get a response back:

Response (Body Content JSON)

{
   {
    "data": {
        "query": {
            "xray": "$VALUE_STARS >= 5 & $STABILITY_STARS >= 5 & $PROFITABILITY_STARS >= 5"
        },
        "xray_parameters": {
            "normalization_universe": "GLOBAL",
            "instrument_universe": "GLOBAL",
            "group_split_type": "REGION_SECTOR"
        },
        "instruments_predefined": [],
        "sorting_variables": {
            "xray": [
                "VALUE"
            ],
            "reference": [],
            "derived": [],
            "sorting_order": [
                "VALUE"
            ],
            "ascending": false
        },
        "instruments": [
            {
                "isin": "US05684B1070",
                "name": "Bain Capital Specialty Finance Incorporated"
            },
            {
                "isin": "US0207641061",
                "name": "Alpha Metallurgical Resources Incorporated"
            },
            {
                "isin": "US92343V1044",
                "name": "Verizon Communications"
            },
            ...
        ]
    },
    "meta": {}
}
}

Field	Description	Data type	Example	Required
`query`	A dictionary containing the filters by filter type.	`dict`	{"xray": "$VALUE_STARS >= 5}	yes
`sorting_variables`	The sorting logic of the output payload.	`dict`	{"xray": ["VALUE"], "sorting_order": ["VALUE"]}	no
`xray_parameters`	The parameters for the X-Ray set to be used in the query.	`dict`	{"normalization_universe": "GLOBAL", "instrument_universe": "GLOBAL", "group_split_type": "REGION_SECTOR"}	no
`instruments`	A dictionary containing the instruments passing the filters.	`list`	[{"isin": "US92343V1044", "name": "Verizon Communications"}]	yes