Skip to main content

benecaster_get_downloads_by()

Free 
benecaster_get_downloads_by( string $dimension, int $show_id, array $args = [] ): array

Returns a show’s tracked downloads broken down by tier, podcast app, day or episode. These are the breakdowns Benecaster’s own Downloads panel draws, from the same calculation, so a chart built on this cannot disagree with it. Downloads older than about 30 days are included, from Benecaster’s daily totals.

Parameters

Name Type Default Required Description
dimension string — Yes What to break the downloads down by: tier, app, day or episode.
show_id int — Yes WordPress post ID of the show.
args array [] No Optional. The same episode_id, date_from and date_to as benecaster_get_download_total(). For the episode dimension only: limit, the number of top episodes to return (default 10, at most 100); episode_id does not apply to it.

Return Value

Type: array

A list of rows, largest count first except where noted. tier → tier_slug and count, with downloads from the public feed under public. app → app and count. day → date and count, UTC days, oldest first; days with no downloads are left out, not padded with zeros. episode → episode_id and count, the show's top episodes. An empty list for an unknown dimension.

Example

$by_app = benecaster_get_downloads_by( 'app', $show_id, [
    'date_from' => gmdate( 'Y-m-d', strtotime( '-90 days' ) ),
] );
foreach ( $by_app as $row ) {
    printf( '<li>%s: %s</li>', esc_html( $row['app'] ), esc_html( number_format_i18n( $row['count'] ) ) );
}

Hooks Fired

Notes

Every rule of benecaster_get_download_total() applies: the figures are tracked downloads, a floor rather than the audience; dates are UTC and inclusive; an episode_id that is not an episode of the show gives nothing; and a malformed date gives nothing and raises a _doing_it_wrong() notice. An unknown dimension returns an empty list and raises the same notice.

There is no hour-of-day or weekday breakdown. The daily totals keep no time of day, so such a chart could only ever cover the last 30 days. If you build one yourself, convert to the site's timezone before grouping, never group on the UTC value.

The app names come from the benecaster_download_app_patterns filter. There is no capability check.

Need this built rather than just documented? See our services →