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

Your API secret is not used with this endpoint.

Note: Profile data is kept for 7 days

GET /related

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 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

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

Your API secret is not used with this endpoint.

Optional Parameters

pub_date_start Publication filter start date; see Date/Time Handling for formatting details. No restriction by default.
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 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.
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.

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

uuid User profile ID to look up history on.
apikey Publisher 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 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?