The Quest for Parity: the latest API updates

If you’ve visited any one of our customer’s sites as a reader, chances are you have experienced how powerful’s API is without even knowing it. It can power content recommendations, personalized newsletters, and trending content slots. Under the hood, it’s pretty cool.  

But sometimes not all features are created equal. One of the downsides of slaying feature requests in the frontend is that the backend takes a while to catch up. If you’ve ever procrastinated over buying new clothes after gaining weight, you know how these things go.  

That’s why we’re excited to announce a prettier picture of parity between our dashboard and the API! In this blog post, we’ll cover three new endpoints and a handful of improvements you’ve been asking for.

New Exclude Endpoint

More data is usually a good thing, until it isn’t. If a post surfaces when it shouldn’t, remove it from your results with the new /exclude  endpoint. You can submit a URL for exclusion, put it back in the game, or display a list of all excluded URLs. Check out our /exclude documentation for further information.

New Metadata Endpoint

Metadata is a big part of what makes our content analytics so powerful. But as your website or your strategy changes, your metadata might too. That’s why we created the new /metadata endpoint that’ll allow you to update metadata on your posts or videos, so you have the final say in what’s what. It requires a secondary secret API Key to use, so check out the /metadata documentation, and reach out to your account manager or for more details.

New Campaigns Endpoint

To keep things as simple as possible, we modeled our campaigns endpoint closely after the dashboard.  

image (31).png

The campaign_key parameter on the /analytics/campaigns endpoint handles toggling between each campaign category.

For example, to see your list of campaigns by campaign ID, make a call to:

GET /v2/analytics/campaigns?

You can either specify campaign_key=id, or leave it off entirely as ID is the default. To return a list of campaign sources, pass campaign_key=source.  

GET /v2/analytics/campaigns?

These lists should provide a great starting point for drilling down deeper. Once you’ve obtained the campaign value of interest, the next step is to filter your posts. The /analytics/posts and /analytics/post/detail endpoints now have the following new filter parameters:

  • campaign_id
  • campaign_medium
  • campaign_source
  • campaign_content
  • campaign_term

To see all posts within the email campaign medium, make a call to:

GET /v2/analytics/posts?

And finally, post details can be filtered by all the campaign keys as well.  

GET /v2/analytics/post/detail?

Filter by Channels

To filter posts and post details by a specific channel – just pass the channel parameter to either endpoint. At the moment, the following three channels are available for filtering – website, amp, fbia.  

GET /v2/analytics/posts?
GET /v2/analytics/post/detail?

Note: The brand new Apple News channel is not yet ready for primetime in the API, so subscribe to our newsletter below so we can let you know when that time comes.

Filter by Multiple Tags, Authors, and Sections

It’s now possible to filter your posts by more than one author, tag, or section. To see all posts with both the tesla and ev tags, make a call to:  

GET /v2/analytics/posts?

We currently allow a maximum of five authors, sections, or tags per query to help you find exactly what you’re looking for.  

More Sorting Options for Post Details

While the /analytics/posts endpoint allowed for sorting by all available metrics, our /analytics/post/detail endpoint was previously limited to only views and visitors. This discrepancy has now been lifted, so sort away! Send us your favorite metric using the sort parameter and we’ll handle the rest.  

Stay Tuned

Over the coming months, we’ll continue to work hard to deliver features worthy of your attention. We want to know what you’ll build with these new features! Tell us how we can help: