Time series data for Highest Velocity charts?



The Newswhip site displays highest velocity charts for a given article (see screenshot). I am trying to do something similar. I can get close but I don’t see where the API provides all of the data needed to do so.

Here is what I am doing:

Using the /article API, I can get the FB and Twitter data with:

“fb_data”: {
“total_engagement_count”: 2712
“tw_data”: {
“tw_count”: 167

And the highest velocity score with:

“max_nw_score”: 359.824385165805,

However, what is missing from the API is the time series data that shows the velocity rising over a period of time. Is there any way to get that data from the API?

Here is a second screenshot which shows the varying non-linear shapes of the velocity chart:



Hey @maarkdev! Thanks for posting.

At the moment, we don’t expose time series data for any of our data points, which includes velocity. The only way to achieve this at the moment would be to call our API regularly and store the result each time. You can use the delta_period value, which shows how frequently we’re refreshing the data, to keep the number of requests down.

Obviously, that’s not an awesome solution. We know that people have similar goals to you, and making it easier to create charts like this is something we’re looking at. It’s wrapped up in this work from our roadmap: https://developer.newswhip.com/docs/research-api-use-cases

Sorry that’s not quite what you were probably hoping for, but I hope that answer helps get you started for the moment. I’ll keep an eye out for any follow up questions or additional feedback!



Thanks for the info. Concerning the workaround idea, I looked into a similar idea using the to/from params. However, I discovered to and from range only includes the articles that are published within that time range. Therefore, if an article was published on 5/10 and you are running the query on 5/17, then the article will show up if you do the default search (today to -7) or a date range that includes 5/10 (e.g., 5/10 to 5/11). However, if you do 5/12 to 5/13 as the date range, that article will not appear in the result set. What’s more, if you do a to/from query or the default query, the scores are always the same. So, how would doing regular API calls provide different results? Thanks!


The social scores provided in the API response refresh based on the time provided in the delta_period, and the API always returns the latest values. Velocity is recalculated every time the social data is refreshed.

If you are just looking at max_nw_score, then that probably won’t change too frequently. That shows the highest velocity that a piece of content has ever had. nw_score shows the current velocity.

With that in mind, making regular calls and storing the nw_score value will give you the data you need for the graph.

Keep in mind, after 7 days we stop refreshing these values, so I’d suggest that anything that falls outside of the default query range of 1 week is not worth looking up unless you need the final velocity value.