Keyword Search¶
Keyword Search Calls
POST keywords/search¶
Execute a search of the eContext Keyword Dataset and retrieve matching keywords. Returns a result_id to the GET keywords/search/:result_id call. This call creates a new result resource that will be available for either 2 days or until consumption.
This function accepts two distinct types of queries:
- By Category (
"type":0
): Searches for keywords belonging to a specified category node (category only) or branch (category + descendants). - By Keyword (
"type":1
): Searches for keywords containing the words (including stemmed variants) of the input query.
See query and type description for formatting details.
Parameters¶
Parameter | Type | Description |
---|---|---|
query (required) | mixed | The query string, if search by Keyword, or an array of categories if searching by Category. If searching by Category, the query should be an array of key->value pairs where the key is the Category id and the value is a boolean, selecting the entire branch if set to true , or just the node, if set to false . |
type (required) | enum | What type of search is being performed. (0 = by Category, 1 = by Keyword) |
filters (optional) | array | Filters to be applied to this search. For more information please see section on Keyword Search Filters |
pagesize (optional) | integer | The number of keywords to show on a single result page. Default value is 1,000 |
limit (optional) | integer | The maximum number of keywords to return. There is a system maximum of 500,000. Default value is 25,000 |
Example Request By Keyword¶
POST Request¶
curl -X POST -u username:password --data-binary @keywords-search-a-input.json \ --header "Content-type: application/json" \ https://api.econtext.com/v2/keywords/search
The contents of keywords-search-a-input.json
:
{
"query":"hello world",
"type":1,
"limit": 25000,
"pagesize": 250,
"filters":{
"filters":[
{"filter":3, "value":[1, 2, 4, 16, 32, 64, 128, 256, 512], "invert":false}
]
}
}
POST Response¶
{
"econtext": {
"keywords": {
"count": 4086,
"pagesize": 250,
"pages": 17,
"limit": 25000,
"searchid": "7765ebd5f81ee17bd79cf5fbf650fc1379cf5251f4a090006250b796331a668b"
},
"signature": {
"resource": "GET /categories/map/:keyword",
"status": "200 OK - successful",
"client_ip": "127.0.0.1"
}
}
}
Example Request By Category¶
POST Request¶
curl -X POST -u username:password --data-binary @keywords-search-b-input.json \ --header "Content-type: application/json" \ https://api.econtext.com/v2/keywords/search
The contents of keywords-search-b-input.json
:
{
"query":{
"ac0fb32ea52f2c1228592ad6598c2cc2":false,
"eee9032c21b71047f1f3252565bfaf58":true
},
"type":0,
"limit": 25000,
"pagesize": 20,
"filters":{
"filters":[
{"filter":3, "value":[1, 2, 4, 16, 32, 64, 128, 256, 512], "invert":false}
]
}
}
POST Response¶
{
"econtext": {
"keywords": {
"count": 25000,
"pagesize": 20,
"pages": 1250,
"limit": 25000,
"searchid": "63c48c6eb0e25572fdd0f872a04f60c6377365cb2e9687bbbe39631b258ec289"
},
"signature": {
"resource": "GET /categories/map/:keyword",
"status": "200 OK - successful",
"client_ip": "127.0.0.1"
}
}
}
GET keywords/search/:result_id¶
Return keywords from the specified search. Each keyword contains a category_id that maps to a
Category in the associated “categories” dictionary. A null
value in the category_id
indicates that the keyword is currently unmapped to the eContext Taxonomy.
Parameters¶
Parameter | Type | Description |
---|---|---|
result_id (required) | string | The identifier specifying which search to return results from. The result_id is included in the response from a successful POST keywords/search call. |
page (optional) | integer | Specify which page to retrieve results from. If no page is specified, a default value of 1 is used. Indexing for pages begins at 1 . |
Example Request¶
GET Request¶
curl -X GET -u username:password \ https://api.econtext.com/v2/keywords/search/63c48c6eb0e25572fdd0f872a04f60c6377365cb2e9687bbbe39631b258ec289?page=1
GET Response¶
{
"econtext": {
"keywords": {
"cursor": {
"pages": 1250,
"current": 1,
"next": 2
},
"keywords": [
{
"keyword": "breaking bad",
"volume": 1680000,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking-bad",
"volume": 412500,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad season 6",
"volume": 82500,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad cast",
"volume": 67875,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad season 5",
"volume": 37125,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad recap",
"volume": 24825,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad wiki",
"volume": 24825,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad alternate ending",
"volume": 20325,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad episodes",
"volume": 20325,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad season 1",
"volume": 20325,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad season 5 episode 9",
"volume": 20325,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad action figures",
"volume": 16650,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad review",
"volume": 16650,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad season 2",
"volume": 16650,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad season 5 episode 13",
"volume": 16650,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad season 5 episode 14",
"volume": 16650,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "how many seasons of breaking bad",
"volume": 16650,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad complete series",
"volume": 13575,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad merchandise",
"volume": 13575,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
},
{
"keyword": "breaking bad poster",
"volume": 13575,
"category_id": "ac0fb32ea52f2c1228592ad6598c2cc2"
}
],
"categories": {
"ac0fb32ea52f2c1228592ad6598c2cc2": {
"id": "ac0fb32ea52f2c1228592ad6598c2cc2",
"name": "Breaking Bad",
"path": [
"Arts & Entertainment",
"Movies & Television",
"Movie & TV Products",
"TV",
"Drama TV Shows",
"Breaking Bad"
],
"idpath": [
"0cc9e1516aaa38d4802a2ee5314ac4ab",
"06b7167107de9cff93e6738da9c044c4",
"8e4e953b861d4597cb5fae3b7de67ce5",
"b3728edb10af57dfbd941132f0c932ae",
"153fd544b9063cfdbe86aaf1b04882b4",
"ac0fb32ea52f2c1228592ad6598c2cc2"
],
"stats": {
"social_relevance": 0.0000381826,
"social_idf": 21067.359562841
}
}
}
},
"signature": {
"resource": "GET /keywords/search/:search_id",
"status": "200 OK - successful",
"client_ip": "127.0.0.1"
}
}
}