Feature request: simple JSON view

[jamescridland]

Hello!

I'm looking for a JSON output that would return four numbers, with four pieces of associated metadata, in a JSON object:

     ('seven-day-downloads'),
     ('seven-day-downloads-asof'),
     ('thirty-day-downloads'),
     ('thirty-day-downloads-asof'),
     ('downloads-count'),
     ('downloads-period'),
     ('audience-count'),
     ('audience-period')

I guess either this could be via an API call, and be a new portion of /worker/routes/api_queries.ts - or it could be just an alternate view of the main show page, in which case the URL could be as simple as /show/55f8007aec094899a02fd44273aa6558/headline.json (with perhaps a last-built date field).

This would enable a quick method of retrieving this headline data, which is lacking (and, selfishly, would allow me to retire a chunk of analytics code that I'm currently running myself).

It strikes me that if this were an alternate view of the main show page, it needn't use an API key and be simpler to produce; and given it's not private data in any way, shouldn't really need an API key to view this information. But I don't know which you'd prefer, given your infrastructure. Which would work better, and is there a way I can help with that?

[johnspurlock-skymethod]

Thanks for the suggestion James, I'll take a look. Probably should be precomputed during the daily stats pass and returned via an api subendpoint for the show, something like /api/1/shows/<show-id>/headline-stats

If you are in a pinch for time, you can grab the stats for the show and compute it yourself (this is what the show stats pages do) using the undocumented show stats endpoint. It's not documented yet since it may change a bit before I'm ready to commit to the api in the public docs.

e.g. show stats for podnews daily
https://op3.dev/api/1/shows/55f8007aec094899a02fd44273aa6558/stats?token=preview07ce

There are a few optional params if you need to go back in time more than a few months, see the searchParams parsing in the method implementation for what they do.

[jamescridland]

Thank you. That's quite the data dump! Goodness.

I'd be very happy to help with the headline stats API call if I knew how. My suspicion is that this could be a very cheap API call, and could even be used in directories.

[daveajones]

Once you settle on something I’d like to interface with these stats for PI as well. Good call @jamescridland

[johnspurlock-skymethod]

@jamescridland just to clarify, you're looking for those 4 existing show-level metrics (and associated time ranges) at the top of each OP3 show stats page?

I've wanted a way to compute an episode-level 30-day download number for a while, since this is the number most folks look at for $$$ purposes, and doesn't bias based on publishing frequency. This number is a bit trickier to compute, since each episode has different numbers (maybe a mean+variance would be better, or simply the latest episode that has reached 30 days).

Anyway if I'm running over each show to precompute those existing headline box stats, perhaps I could use this as an excuse to start computing this number as well.

[jamescridland]

Yes please.

(My assumption is that from 2 Sep 00:00 GMT, given a day for calculation, I could invalidate a cache and see August's numbers.)

[johnspurlock-skymethod]

Ok, from what I'm hearing, how about we start small:

{
  "lastCalendarMonthDownloads": 123123,
  "lastCalendarMonthAudience": 12345,
  "lastCalendarMonth": "yyyy-mm"
}

Callers will have to deal with normalizing months with different numbers of days if doing month-to-month comparisons

[johnspurlock-skymethod]

Ok first pass is up: https://op3.dev/api/1/shows/<show-id>/summary-stats?token=<token>

[jamescridland]

"show-id" is the Guid?

So for https://op3.dev/show/396d9ae0-da7e-5557-b894-b606231fa3ea the summary stats are at

https://op3.dev/api/1/shows/396d9ae0-da7e-5557-b894-b606231fa3ea/summary-stats?token=preview07ce

?

[johnspurlock-skymethod]

It's the immutable OP3 show uuid, you can look it by podcast guid with: https://op3.dev/api/docs#tag/shows/operation/viewShowInformation