API v2¶

July 2017¶

Added full_content_word_count to post metadata. This will allow you to filter recommendations by length or calculate read time.

{
    "data": [
        {
            "title": "Breaking News",
            "author": "Joe Author", 
            "full_content_word_count": 507,
            // Other fields
        }],
    "success": true,
    "meta": {...},
    "links": {...}
}

June 2017¶

Parse.ly has updated our API to bring more metrics and closer alignment to the JSON API community standards. This update requires no changes for existing code, though slight changes will be needed to take advantage of the new functionality. The API URL,api.parsely.com/v2, does not change.

New Metrics¶

The sort parameter has been expanded to allow for more metrics. Please see the documentation for analytics.

• Mobile, tablet, and desktop breakdowns of views
• New and returning breakdowns of visitors
• Engaged time, including engaged time for new and returning visitors
• Social interactions for Facebook, Twitter, LinkedIn, and Pinterest
• Social referrals for Facebook, Twitter, LinkedIn, and Pinterest

On all requests you will be returned a metrics object that contains the metric in the sort parameter and its value. For metrics that are derivatives of other metrics, such as the average engaged time, you will receive the values that were used in the calculation without needing a second query.

{
    "data": [
        {
            "title": "Breaking News",
            "author": "Joe Author", 
            "metrics": {
                "avg_engaged": 2.793, 
                "engaged_minutes": 162, 
                "views": 75, 
                "visitors": 58
            }, 
            // Other fields
        }],
    "success": true,
    "meta": {...},
    "links": {...}
}

The new top-level meta object contains a record of what fields were returned in each result, as well as how the results were overall sorted.

{
    "data": [
        {
            "metrics": {
                "avg_engaged": 2.793, 
                "engaged_minutes": 162, 
                "views": 75, 
                "visitors": 58
            }, 
            // Other fields
        }],
    "success": true,
    "meta": {
        "metrics": [
            "engaged_minutes",
            "avg_engaged",
            "visitors",
            "views"
        ],
        "sort": "avg_engaged"
    },
    "links": {...}
}

Developer Notes: The _hits field on records is not applicable to new metrics, since they are not pageviews. If new metrics (not views, visitors, or _hits) are requested in the sort parameter, the _hits field will not be present. Using the new metrics object will allow you to re-use handling code on all requests, regardless of the sort parameter.

Better Searches¶

Searches via the /search and /related endpoints can now be sub-sorted according to the same metrics as /analytics. This gives you more power in customer recommendations, as you can boost popular posts about a topic in the search results.

The new boost parameter is used in lieu of the strategy and click parameters currently being used by those endpoints.

Flexible Time Ranges¶

We have moved to provide more flexibility in how time is declared in the API. The period_start, period_end, pub_date_start, and pub_date_end parameters now support more formats:

• Year-month-day (YYYY-MM-DD). Example: 2012-01-02 for Jan 2nd, 2012. This defaults to your timezone in the dashboard, and is considered end of day (23:59) for end time parameters. This was the only behavior available previously.
• Year-month-day with timezone offset (YYYY-MM-DD±00:00). Example: 2012-01-02-05:00 for Jan 2nd, 2012 EST. For end times, this is assumed to be 23:59 in the specified timezone.
• Year-month-day with time (YYYY-MM-DDThh:mm). Example: 2012-01-02T07:30 for Jan 2nd, 2012 7:30 am.
• Year-month-day with time and timezone (YYYY-MM-DDThh:mm±00:00). Example: 2012-01-02T07:30+00:00 for Jan 2nd, 2012 7:30 am UTC.
• Relative times - m, h, d, w for minutes, hours, days, and weeks, respectively. Example: 15m for 15 minutes ago.

This means that all of your /realtime queries using the time parameter are fully supported by /analytics. We encourage you to move your queries on to the /analytics endpoint, given that you can also control end times, e.g. /analytics/posts?period_start=2d&period_end=1d for a trailing 24 hour window of data.

The [period|pub_date]_start and [period|pub_date]_end parameters are no longer mutually required. End times are assumed to be the current date and time when unspecified, and the start time is assumed to be the limit of what is accessible.

Pagination¶

While the API has always supported multiple pages of results, we've made it easier to follow by adding the top level links object, in alignment with JSON API

{
    "data": [...],
    "success": true,
    "meta": {...},
    "links": {
        "first": "http://api.parsely.com/v2/...&page=1",
        "next": "http://api.parsely.com/v2/...&page=3",
        "prev": "http://api.parsely.com/v2/...&page=1"
    }
}

Developer Notes:

• first will be available on every request
• next will be available when additional records are available or null otherwise
• prev will be available only past the first page

As a reminder, 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.

Cross Origin Response Sharing¶

Previously the API only supported JSONP through the callback parameter. We’ve now enabled CORS to allow JavaScript access to the API without having to handle JSONP.

Personalized Recommendations - Error Improvements¶

We've aligned the error messages from /profile and /history with the errors from the other endpoints.

Previously you would receive {"error": "missing data"} for errors.

This error key is still available for compatibility, but we have added the fields needed to allow error handling code re-use between endpoints.

Sample error:

{
    "code": 422,
    "error": "missing data",
    "errors": {
        "url": [ "Missing data for required field." ],
        "uuid": [ "Missing data for required field." ]
    },
    "message": "Bad parameters: uuid, url",
    "success": false
}

Personalized Recommendations - Backend improvements¶

We've improved how we handle personalized recommendations (/profile) to give better results in cases where a site visitor repeatedly refreshes a page. This action will no longer reduce the relevancy of recommendations.