GET /search

Note: This endpoint is not enabled by default. Please reach out to to have it enabled.

Search for Posts by keyword or query. These can match against full content. There are 2 strategies one can use to get search results:

  1. recency: Returns search results based on the content of the given link and emphasize fresh articles
  2. click: Beta. 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

Path arguments

q Search query keywords; quoting is supported, e.g. q="squirrel facts" instead of q=squirrel+facts.
apikey Publisher API key

Optional parameters

days Restrict recommendations to articles published within the last n days. There is no restriction by default
pub_date_start Publication date in YYYY-MM-DD format, e.g. 2012-01-01 for January 1, 2012. Must be specified with pub_date_end.
pub_date_end Publication end date; must be specified with pub_date_start, must be greater than that value, and must not be in the future. Note: This value is inclusive, e.g. if pub_date_end is 2012-01-01, it will include articles published up until 2012-01-01T23:59:59Z
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
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=author:"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.
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
sort what to sort the results by. There are currently 2 valid options: score, which will sort articles by overall score and pub_date which will sort results by their publication date. The default is score
callback JSON-P callback, a JavaScript function name that will be used to wrap the JSON response.
Do you have an urgent support question?