This article explains how to perform searches via the API and retrieve search data, including detailed information about search terms, results, and user interactions. Using this API functionality helps you monitor search effectiveness and gain insights into user behavior.

In this article, you’ll learn:

• How to perform searches using the Helpjuice API
• How to retrieve historical searches and related data
• Available filters and parameters to customize your search queries
• How to interpret search API responses
• Best practices for using the search API effectively

Difference Between Performing and Retrieving Searches

Performing a Search

To search for questions using our API, use the following URL:

• Replace test with the desired keyword
• Replace your_account with your subdomain

your_account.helpjuice.com/search?query=test

It's possible to scope the search within a specific language. To do so, just provide the desired language in the URL using the following syntax:

your_account.helpjuice.com/en_US/search?query=test

Example:

[
  {
    "question":{
      "id":163642,
      "name":"Retrieving Answers through API",
      "is_published":true,
      "category_id":7751,
      "account_id":1885,
      "url":"/API/retrieving-answers-through-api",
      "created_at":"2016-06-12T16:50:55.673Z",
      "votes":0,
      "is_internal?":false,
      "slug":"retrieving-answers-through-api",
      "answer_sample":"Note: You're located in section for advanced users. Please use this section only ",
      "long_answer_sample":"Note: You're located in section for advanced users. Please use this section only if you're familiar with API's.Use the following URL to retrieve answers:my_account.helpjuice.com/api/answersIt's possible to scope the answers within a specific language. To do so, just provide the desired language in the URL using the following syntax:my_account.helpju",
      "first_category":"API",
      "categories_display_for_views":"API",
      "parent_categories":[7751,7729],
      "categories":{
        "current":{
          "id":7751,
          "name":"API",
          "url":"/API"
        }
      }
    }
  }
]

Retrieving a Search

Use the following URL to retrieve searches:

• Replace your_account with your subdomain

your_account.helpjuice.com/api/searches

Response:

id,account_id,query,query_without_stopwords,ip,search_count,found_answer,contacted_support,created_at,updated_at,clicked,indexed,readings,found_answers,views

3453162,1885,installing,installing,104.178.174.189,1,true,false,2015-06-19 23:27:43 UTC,2015-06-19 23:27:43 UTC,,true,,,

2816305,1885,installing,installing,50.142.80.121,1,true,false,2015-05-01 00:17:29 UTC,2015-05-01 00:17:29 UTC,,true,,,

2816306,1885,non profit,non profit,50.142.80.121,1,false,false,2015-05-01 00:17:40 UTC,2015-05-01 00:17:40 UTC,,true,,,

3453171,1885,installing,installing,104.178.174.189,1,true,false,2015-06-19 23:27:44 UTC,2015-06-19 23:27:44 UTC,,true,,,

By default, searches will be returned in CSV format. However, it's possible to retrieve them in XLS. To do so, you just need to specify the format in the URL, as follows:

your_account.helpjuice.com/api/searches.xls => to retrieve XLS spreadsheet

Troubleshooting

• Blank response: if you are not seeing any data, or you are receiving a corrupted file (in case of XLS), that's because your Knowledge Base is marked as internally only.
  • Solution: 
    • If you are using a browser to access the data, just sign in before making the request.
    • Otherwise, you'll need to use your Private Key in a request parameter called api_key. See How to Get Your API Key.
      Your query will be similar to this: your_account.helpjuice.com/api/en_US/questions?api_key=MY_KEY

Best Practices

• Use filters like created_at to narrow down results when analyzing searches.
• Monitor common search terms to improve your knowledge base content.