Search

GET /search

Search for Posts by keyword or query. These can match against full content. There are 2 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.
  • boost, which allows use of Parse.ly metrics to determine how rankings are sorted within the results after the initial search has been performed. This parameter is not specified by default, resulting in rankings by relevance only. Only available for sort=score

While this endpoint will work with all languages, the accuracy will be better for documents in the following languages:

  • 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 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=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.
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
Do you have an urgent support question?