Release Notes
#API v2
#January 2020
- Segments have been added to the
/analytics
endpoint, including filtering posts and post details by segment name. See documentation for analytics.
#October 2019
- Added a new public
/top
endpoint to expose Today's Top 10 Posts or Videos for use in building new widgets and integrations. Please see the documentation for Top 10.
#September 2019
-
Added support for requesting up to 5 authors or tags per query. Please see the documentation for analytics.
-
Added support for querying channels and campaigns data from within the
/analytics
endpoint. Please see the documentation for analytics.
#May 2019
- Added support for sorting by all available metrics within the
/analytics/post/detail
endpoint (previously only views & visitors were available).
#December 2018
- Added a new
/metadata
endpoint to allow for directly specifying post and video metadata. Please see the documentation for metadata.
#October 2018
- Added a new
/exclude
endpoint that prevents URLs from appearing in the results of all other endpoints. Please see the documentation for exclude.
#September 2017
- Removed Google+ as a supported network. Requests made to the
/shares/posts/detail
endpoint will return a0
for thego
key. Please see our list of presently supported networks for available options.
{
"data": [
{
"fb": 530,
"go": 0,
"li": 0,
"pi": 1,
"total": 766,
"tw": 235
}
],
"links": {...},
"meta": {...},
"success": true
}
#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 requestnext
will be available when additional records are available ornull
otherwiseprev
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.