Search API Endpoint

0

Being able to easily and quickly search articles for information is perhaps one of the most important aspects of Knowledge Management. 

Using the Search API, you can programmatically search for information either publicly accessible articles, or by articles filtered by a specific group_id that may be assigned to users. There are different types of search criteria that can be used, offering a great deal of flexibility. The search engine (with the exception of the 'exact phrase' search) uses a powerful Natural Language Processing engine to perform optimal searches.


The search object


Attributes

article_id

Unique numeric reference to a matching article. This may be used to identity an article in a number of API calls

This value is immutable and cannot be changed.

title

A descriptive title that is associated with the article and may be displayed in lists when describing articles returned in search results.

slug

Unique string value associated with the article and used as part of the URL.

snippet

A preview or snippet of the text contained within the article. The idea of this is to be able to display a limited amount of text to provide visual context to users reviewing a list of search results.

There is a maximum length returned for this snippet of 400 characters, although you may choose to utilize less than this if needed.

featured

A boolean value of true or false indicating whether the article is marked as 'featured' or not.

Articles that are marked as 'featured' will be show in a special 'featured' list (when enabled) on the knowledge base homepage.

 Language: json
{
	"article_id": 42,
	"title": "article title",
	"slug": "first-article",
	"snippet": "some text content for first article",
	"featured": false
}



⯁


Retrieve a searchGET /search

Returns one or more search objects matching the specified search_phrase, exact_phrase or include_words and optionally exclude_words

Required parameters

At least one of the optional search_phrase, exact_phrase or include_words parameters must be specified


Optional parameters

search_phrase

A string containing one or more words that should be searched for. Results will return articles containing all of these specified words. This search option utilizes the enhanced NLP algorithm

Note that this search option is similar to the default search function performed in your knowledge base

exact_phrase

An exact phrase to be searched for within articles. Note that the search will be performed without case-sensitivity, so capitalization of the phrase does not matter for matching purposes.

Only articles containing this exact phrase will be returned in the search results.

include_words

A string containing one or more words that should be searched for. Results will be returned for articles containing any of the words specified in this parameter, with the exception of any words contained in the optional exclude_words parameter.

This search option utilizes the enhanced NLP algorithm

exclude_words

This parameter can only be used when the include_words parameter is used.

A string containing one or more words that should be excluded from the search, meaning results will NOT be returned for articles containing any of the words specified in this parameter.

This parameter can be particularly useful when working with common include_words, allowing you to narrow the search further by avoiding articles containing certain words, when you are sure these would not be appropriate for your search

group_id

When this option is specified, search results will be filtered to only return matches with the group(s).

This means the group_id values must be valid for the account. Only categories (and articles within them) associated with the group_id value(s) specified (defined by Category Group settings) will be searched.

If this parameter is not specified, then only categories (and their articles) within any groups that are marked with the public_access flag will be searched.

The numeric value of the group_id should be specified. If more than one group is included, these should be specified as a string separated by commas  - for example:  "group_id": "123,124,125"

limit

Optional limit on the number of objects to be returned, between 1 and 100

If this parameter is not provided, a default limit of 100 will be applied, returning the maximum of 100 items.

fetch_offset

A cursor to use for pagination. Defines the numeric offset from where results should begin being fetched.

For example, if you were working with a large number of records, and wanted to fetch them in pages of 10 at a time, you might set the limit value to 10 (indicating only 10 records at a time should be returned) and for the first page, fetch_offset would be 0 to indicate no offset (returning records 1-10).

For the second page, fetch_offset would be set to 10, allowing records 11-20 to be returned.

If this parameter is not provided, a default fetch_offset of 0 will be applied, returning records from the start of the result set.

 Language: bash [ Line Numbers Enabled ]
curl -X GET https://api.gogoworx.com/search \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"search_phrase": "hello world", "group_id": 123, "limit": 2}'

Response (containing specified articles):

 Language: json
[{
	"article_id": 42,
	"title": "article title",
	"slug": "first-article",
	"snippet": "some text content for first article",
	"featured": false
},
{
	"article_id": 43,
	"title": "second article title",
	"slug": "second-article",
	"snippet": "some text content for second article",
	"featured": true
}]



⯁


Example Use Cases

There are a number of ways in which the Search API can be used, however a couple of examples may be helpful as a guide.



Anonymous User Search

When performing a programmatic search on behalf of an anonymous (not logged in or unregistered) user, then it would be appropriate to not specify the group_id, thereby only returning article matches that are contained within articles marked with the public_access flag, as shown here:

 Language: bash [ Line Numbers Enabled ]
curl -X GET https://api.gogoworx.com/search \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"search_phrase": "hello world", "limit": 2}'

Note that in this example, group_id is not specified in the parameters



Registered User Search

If you would like to perform on behalf of a particular user that is registered in your account, you can use the User Group API Endpoint to determine the group_id values of the groups that user is associated with. This may be none (in which case the anonymous search would be performed), or it may be one or more groups.

Once you know which groups are associated with a user, you can pass these as a comma-separated list to the search API endpoint to return article matches from any of those specified groups, in exactly the same way as that user would see when searching via the web portal, as shown here:

 Language: bash [ Line Numbers Enabled ]
curl -X GET https://api.gogoworx.com/search \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"search_phrase": "hello world", "group_id": "123,124,125", "limit": 2}'

Note that in this example, group_id is specified as a comma-separated string in the parameters