Parse.ly’s API now supports audience segments
Parse.ly has supported custom audience segments in the Analytics dashboard for a while now, but product teams haven’t been able to use segments to build internal tools or create customized site experiences. That changes today with API support for audience segments!
First, a quick introduction for those who are uninitiated. Audience segments allow you to zoom in and see a subset of your visitors using any criteria you’d like. Want to look at what visitors in Canada read versus those in the United States? No problem. Understand what content really matters to just your paying subscribers? We’ve got you covered.
(If you’re curious about adding segments to your account, contact hello@parsely.com and we’d be happy to give you a hand).
If you use Parse.ly’s API and have segments enabled in your account, you’ll now be able to use the /analytics endpoint to perform two kinds of queries:
- See top posts for an individual segment.
- See traffic across all your segments.
Top Posts within a Segment
In the example above, there was a “Paid Subscribers” segment defined. What if we want to know what these paid subscribers are reading in order to display a “Popular with Subscribers” widget on our site? Easy!
GET https://api.parsely.com/v2/analytics/posts?apikey=<your apikey>&secret=<your secret>&segment=Paid+Subscribers&metrics=views
{
"data": [
{
"_hits": 35422,
"author": "Bob Smith",
"authors": [
"Bob Smith"
],
"full_content_word_count": 1372,
"image_url": "https://example.com/iqjWHBFdfxIU/itxthAhXDALA/v1/1200x899.jpg",
"link": "https://www.example.com/news/features/2020-02-05/article-1?itm_source=parsely-api",
"metadata": "",
"metrics": {
"views": 35422
},
"pub_date": "2020-02-05T10:00:11",
"section": "my section",
"tags": [
"A",
"B",
"C"
],
"thumb_url_medium": "...",
"title": "News Article Title",
"url": "https://www.example.com/news/features/2020-02-05/article-1?itm_source=parsely-api"
},
...
],
"links": {
"first": "https://api.parsely.com/v2/analytics/posts?apikey=<your apikey>&secret=<your secret>&segment=Paid+Subscribers&page=1",
"next": "https://api.parsely.com/v2/analytics/posts?apikey=<your apikey>&secret=<your secret>&segment=Paid+Subscribers&page=2"
},
"meta": {
"metrics": [
"views"
],
"sort": "views"
},
"success": true
}
You can combine the segment filter with other filters like publish dates, tags, authors or sections as well as sorting by different metrics to open up a wide range of possibilities (e.g articles published today that are popular with the “Paid Subscribers” segment).
If you’re building something with this endpoint, please let us know, we’d love to hear how you’re using this and what we can do to improve.
Getting Traffic for all Segments
The https://api.parsely.com/v2/analytics/segments endpoint allows you to see traffic for all active segments in your account (very similar to the segments listing page in the dashboard).
This is handy if you’re thinking of building an internal tool to track say active subscribers for the day (unique visitors by segment).
GET https://api.parsely.com/v2/analytics/segments?apikey=<your apikey>&secret=<your secret> { "data": [ { "metrics": { "views": 1379374 }, "segment": "Paid Subscribers" }, { "metrics": { "views": 1372225 }, "segment": "Canada" } ], "links": { "first": "https://api.parsely.com/v2/analytics/segments?apikey=<your apikey>&secret=<your secret>&page=1", "next": null }, "meta": { "metrics": [ "views" ], "sort": "views" }, "success": true }
Remember that you can sort by metrics other than views by appending a sort parameter to the query string (check out the full list of available metrics to sort by).
What else is new in Parse.ly’s API?
We recently added API support for campaigns and channels and a new /top endpoint that allows you to easily grab the top 10 posts or videos to power a “Most Read” widget. Check out our release notes for more info.