Big Content Search API Documentation

Big Content Search Integration Opportunities

Our database offers unlimited opportunities – for members and partners. See who integrates with our API on our Integration Opportunities page.

BCS WebServices API

BCS WebServices API is used by sending a HTTP POST request to https://members.bigcontentsearch.com/api/<service_name>.

Authentication is performed on every service call by checking each request for two paramaters:

After each request the API returns the HTTP OK (200) and a JSON response. The response contains three fields:

  • status_code: 0 for success, some other number if an error occurred
  • response: content of the response, only valid if status_code is 0
  • error_msg: error message, only valid if status_code is not 0

An example of a successful response:

{ "status_code": 0,
					  "response": "This is response body - 'return value' of the service call",
					  "error_msg": "" }
					

An example of a failed response:

{ "status_code" : 3,
					  "response" : "",
					  "error_msg" : "Required parameter username not provided." }
					

The status code to description mapping is:

Code Description
0 OK.
1 Internal service error.
2 Service not found.
3 Missing parameter.
4 Invalid parameter value.
8 Authentication error.
9 Not implemented yet.
100 No articles found for given search term.
110 Daily download limit reached.
130 Creating a new member failed.

Test request

To quickly test WebServices API, use curl or a similar tool:

curl -d "username=<YOUR_USERNAME>&api_key=<YOUR_API_KEY>&search_term=<SEARCH_TERM>" https://members.bigcontentsearch.com/api/article_get_by_search_term

Always requesting new articles

Use-case: A user of BCS WebServices API wants to request articles that he/she has not yet downloaded, so his/her content is always unique.

Possible implementation: search results numbering. We could number the search results and allow the user to specify how much articles to ignore, or better yet, at which search result page to start returning articles. However, this implementation has a pitfall: we are constantly tweaking our search algorithms and adding new articles to the database. Hence, an article that is today on page 2, might be on page 3 tomorrow. And the user would download the same article twice.

Improved implementation: to avoid the above described pitfall, we decided to allow the user to track downloaded articles by their Unique-ID (UID). To support this, the API always returns the UID of the article along with it’s title and text. This enables the user to keep a local list of already downloaded articles. Then upon every new request for an article, the users sends the list of UIDs of articles he/she already has. The API will take this list into consideration when deciding which article to return next. This list is passed as the ids_to_skip optional parameter, which should be formatted as a list of strings.

Available services

ApiView.ping()[source]

A simple service used for testing purposes.

Ping is a very simple service that always responds with pong. It doesn’t do any authentication checks, nor does it require any parameters. It’s used to quickly test if one can successfully send a POST request to BCS API.

Returns:pong
Return type:JSON
ApiView.article_count_by_search_term()[source]

Number of articles in our DB for a search term.

This service searches our database for articles based on the given search term. It returns the number of articles found.

Parameters:
  • username (string) – username for API access
  • api_key (string) – key for API access
  • search_term (string) – search term to query our database for
  • ids_to_skip (JSON formatted array of strings) – (optional) list of article UIDs to exclude from the search results set
  • titles_only (boolean) – (optional) search in titles only, defaults to False
Returns:

number of articles found for search term

Return type:

JSON string

ApiView.article_get_by_search_term()[source]

Get article for a search term.

This service searches our database for articles based on the given search term. It returns the most relevant article found. If no article is found it returns status code 100 (no article found).

Parameters:
  • username (string) – username for API access
  • api_key (string) – key for API access
  • search_term (string) – search term to query our database for
  • ids_to_skip (JSON formatted array of strings) – (optional) list of article UIDs to exclude from the search results set
  • spin (boolean) – (optional) spin article as well, defaults to False
  • titles_only (boolean) – (optional) search in titles only, defaults to False
Returns:

title, text and UID of an article

Return type:

JSON string

ApiView.articles_get_by_search_term()[source]

Get articles for a search term.

This service searches our database for articles based on the given search term. It returns the most relevant articles found. If there is a request for e.g. 100 articles and only 20 found the API will return 20 articles. If no article is found it returns status code 100 (no article found).

Parameters:
  • username (string) – username for API access
  • api_key (string) – key for API access
  • search_term (string) – search term to query our database for
  • count (int) – number of articles to return
  • ids_to_skip (JSON formatted array of strings) – (optional) list of article UIDs to exclude from the search results set
  • spin (boolean) – (optional) spin article as well, defaults to False
  • titles_only (boolean) – (optional) search in titles only, defaults to False
Returns:

list of dictionaries with fields title, text and UID of articles

Return type:

JSON string

ApiView.member_create()[source]

Create a new site member.

This service enables you to create a new member. You need to have a special permission to use this service.

The member_data parameter describes the new member that is to be created. It supports the following keys:

  • fullname - Full name of the new member
  • email - Email of the new member
  • product_id - ID of purchased product
Parameters:
  • username (string) – username for API access
  • api_key (string) – key for API access
  • member_data (JSON formatted key/value pairs) – data describing the new member
Returns:

True if member was created.

Return type:

Boolean