Tech docs
API Docs
Recommendations

Recommendations

#secret parameter not required

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

#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

uuidUUID for user profile being trained.
urlCanonical URL for page being trained against profile.
apikeyPublisher API key

Your API secret is not used with this endpoint.

Note: Profile data is kept for 7 days by default. Contact value@parsely.com for information about extending retention limits.

#GET /related

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

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

This endpoint takes two notable optional parameters:

  • 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

This allows you to find relevant recommendations but organize results to promote, for example, popular social stories.

#Query Parameters

urlCanonical URL to use as the basis for contextual recommendations. Cannot be specified with uuid.
uuidUser profile ID to use as the basis for personalized recommendations. Cannot be specified with url.
apikeyPublisher API key

Your API secret is not used with this endpoint.

#Optional Parameters

pub_date_startPublication filter start date; see Date/Time Handling for formatting details. No restriction by default.
pub_date_endPublication filter end date; see Date/Time Handling for formatting details. Defaults to current date and time if not specified.
limitNumber of records to retrieve; defaults to "10".
pagePage number to retrieve if multiple pages are available; defaults to 1. Retrieving a page that is unavailable returns an empty record list.
sectionReturn recommendations that belong only in the specified section
authorReturn recommendations that only belong to the specified author
tagReturn recommendations that only belong to the specified tag
sortWhat 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
excludeExclude 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_resultsBy 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.
callbackJSON-P callback, a JavaScript function name that will be used to wrap the JSON response. The API also supports Cross-Origin Response Sharing.

The maximum pagination limit is 2000 records. You will receive an error from the API if you attempt to retrieve past record 2000 through any combination of page and limit.

#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

uuidUser profile ID to look up history on.
apikeyPublisher API key

Your API secret is not used with this endpoint.

#Examples

#Contextual

Contextual Recommendations use a URL as input and return a list of relevant Posts as output.

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...
    ]
}

#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...
  ]
}
rocket emoji