API: Search endpoint use and overview

secret parameter not required

The endpoint on this page is designed to be used in-browser (called via JavaScript), so no API secret is necessary.

GET /search

Search for Posts by keyword or query. These can match against full content. Notable parameters one can use to control search results:

• sort, which determines the posts returned. _score (default) selects by relevancy. pub_date selects relevant posts by publish date.

While this endpoint will work with all languages, the accuracy will be better for documents in the following languages (read more about language support here):

• Arabic
• Armenian
• Basque
• Bulgarian
• Catalan
• Chinese
• Czech
• Danish
• Dutch
• English
• Finnish
• French
• German
• Greek
• Hebrew
• Hindi
• Hungarian
• Indonesian
• Italian
• Japanese
• Korean
• Norwegian
• Persian
• Portuguese
• Romanian
• Russian
• Spanish
• Swedish
• Turkish

Query Parameters

apikey	Publisher Site ID (API key)

Your API secret is not used with this endpoint.

Optional Parameters

q	Search query keywords; quoting is supported, e.g. q=”squirrel facts” instead of q=squirrel+facts.
pub_date_start	Publication filter start date; see Date/Time Handling for formatting details.
pub_date_end	Publication filter end date; see Date/Time Handling for formatting details. Defaults to current date and time if not specified.
limit	Number of records to retrieve; defaults to “10”.
page	Page number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list.
section	Return recommendations that belong only in the specified section
author	Return recommendations that only belong to the specified author
tag	Return recommendations that only belong to the specified tag
sort	What to sort the results by. There are currently 2 valid options: score, which will sort articles by overall relevance and pub_date which will sort results by their publication date. The default is score
boost	(Available for sort=score only). Sub-sort value to re-rank relevant posts that receieved high e.g. views; default is undefined (score only). See Available Metrics for complete list of options
exclude	Exclude recommendations from a certain author, section or tag. The syntax is exclude=<meta>:<meta-value>, where meta is one of authors, section, or tags. To exclude all recommendations by author “Bob Yu”, the syntax would look like this: exclude=authors:"Bob Yu". You can pass this parameter more than once. For example, to exclude all articles by author “David Austin” tagged “football”, you would pass exclude=authors:"David Austin"&exclude=tags:"football" in the request.
callback	JSON-P callback, a JavaScript function name that will be used to wrap the JSON response. The API also supports Cross-Origin Response Sharing.

Deprecated Optional Parameters

Please use sort and boost, as they provide the below functionality and more.

strategy	The algorithm to use for search. The default is recency
click	method: one of ref_social, ref_search, ref_internal. Must be specified when strategy is click

1. recency: Returns search results based on the content of the given link and emphasize fresh articles
2. click: Returns search results based on the content of a link and give higher importance (“boost”) to links with certain click kinds of click data. Since multiple sources of click data are available, this must be specified with click.method.

Possible values for click.method:

• ref_social: boost results by number of social referrers from Facebook, Twitter, Pinterest (“viral content”)
• ref_search: boost results by number of referrers coming from search engines (“informative content”)
• ref_internal: boost results by number of referrers coming from within the site itself (“editorially promoted content”)
• shares: boost results by number of shares a post has received