Keyword Search

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.

Resource URL

https://api.econtext.com/v2/keywords/search

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.

Resource URL

https://api.econtext.com/v2/keywords/search/:result_id

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"
    }
  }
}