Recommendations

GET /profile

Train a user profile for the purpose of personalized recommendations. Use :http:method:related to return recommendations using the same UUID as specified here.

Query Parameters

uuid UUID for user profile being trained.
url Canonical URL for page being trained against profile.
apikey Publisher API key

Note: Profile data is kept for 7 days

GET /related

Note

This endpoint is not enabled by default. Please contact support@parsely.com to have it enabled.

Retrieve a list of Post recommendations for a specified profile UUID (trained in :http:method:profile) or a specified canonical URL.

Note

If no results are found, by default the most recent articles are returned. You can change this behavior buys specifying the respect_empty_results parameter.

There are 2 strategies one can use to get search results:

  • recency: Return search results based on the content of the given link and emphasize fresh articles
  • click: Beta Return search results based on the content of a link and give higher importance ("boost") to links with certain 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

Query Parameters

url Canonical URL to use as the basis for contextual recommendations. Cannot be specified with uuid.
uuid User profile ID to use as the basis for personalized recommendations. Cannot be specified with url.
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, and must be greater than that value. 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
strategy The algorithm to use for recommendations. The default is recency
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 looke 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.
respect_empty_results By default, if no recommendations are found, the API returns the most recent articles. Passing this parameter with a value of 1 will return an empty result if no recommendations are found.
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.

GET /history

Retrieve a list of URLs visited by a user by UUID. This is the training profile being used for personalized recommendations.

Query Parameters

uuid User profile ID to look up history on.
apikey Publisher API key

Examples

Contextual

Contextual Recommendations use a URL as input and return a list of relevant Posts as output. The results are not personalized to the individual.

The endpoint for this is :http:method:related and the parameter required is url. Let's say the URL passed is about the Apple iPod. The returned "related" Posts might look like this:

{
    "data": [
        {
            "title": "Ipods And Crime"
            "url": "http://apikey.com/219045/",
            "author": "Kevin Black",
            "section": "Technology",
            "pub_date": "2012-02-20T19:08:00Z",
            "tags": ["apple", "ipod", "crime"]
        },
        // other similar JSON documents...
    ]
}

When using this API, there is no guarantee that the user hasn't already visited the related articles.

Personalized

Personalized Recommendations return Posts relevant to the user's interests, and does not include Posts that the user has already read in the past.

Integrating Personalized Recommendations is slightly more complicated than the above APIs because it requires two steps on behalf of the implementer.

  1. Training. This logs that an individual with a specific UUID has visited a specific URL on your site.
  2. Recommending. Using a saved UUID for the user, return relevant stories from the Parse.ly API.

To train a user profile for your site, use the :http:method:profile endpoint. Pass the uuid and url parameters to log that an individual with that UUID has visited the specified URL.

Generating UUIDs is sometimes a point of confusion for our customers. Parse.ly already generates a UUID for every user using a cookie-based approach. This is accessible on pages with the Parse.ly tracker installed in the field PARSELY.config.parsely_site_uuid. You are free to re-use this UUID for your application if the cookie-based approach is sufficient for you.

However, some customers may have better UUIDs available. If you have e.g. an internal integer ID which also identifies registered/premium users on your site as well as anonymous visitors, this may be a better choice. Parse.ly does not care what the UUID is -- it is simply a string used for identification on further calls to the API.

Once a user is trained, you can view that user's history with /history endpoint. Pass the uuid and you will see the URLs currently associated with that user. This is mainly useful for debugging purposes.

Finally, call the :http:method:related endpoint with the uuid parameter to get personalized recommendations for that user. The default strategy uses a document similarity metric weighted toward most recently seen Posts, and a filter excluding all visited Posts; we plan to introduce additional strategies over time.

Personalized recommendations will appear as multiple posts, similarly to Contextual recommendations. For example, if you train a user on a story about 4G data access plans for mobile phones, you may end up with recommendations like this:

{
    "data": [
        {
            "title": "Verizon announces new 4G phone"
            "url": "http://apikey.com/244232/",
            "author": "John Peters",
            "section": "Technology",
            "pub_date": "2012-03-30T08:26:00Z",
            "tags": ["verizon", "technology", "phones", "4g"]
        },
        // other similar JSON documents...
    ]
}
Do you have an urgent support question?