How do I download a day-by-day export of my JetPack stats⁰?

Luckily, there is an API for downloading all your JetPack stats!

First, get your API key by visiting https://apikey.wordpress.com/ - it should be a 12 character string. For this example, I'm going to use 123456789012. You will need to use your own API key.

There is some brief documentation on that page. Here are the bits we are interested in:

api_key     String    A secret unique to your WordPress.com user account.
blog_uri    String    The full URL to the root directory of your blog. Including the full path.
table       String    One of views, postviews, referrers, referrers_grouped, searchterms, clicks, videoplays.
end         String    The last day of the desired time frame. Format is 'Y-m-d' (e.g. 2007-05-01) and default is UTC date.
days        Integer   The length of the desired time frame. Default is 30. "-1" means unlimited.
limit       Integer   The maximum number of records to return. Default is 100. "-1" means unlimited. If days is -1, limit is capped at 500.
format      String    The format the data is returned in, 'csv', 'xml' or 'json'. Default is 'csv'.

In order to get all of the statistics from a single day, the URl is:

https://stats.wordpress.com/csv.php?api_key=123456789012
     &blog_uri=https://shkspr.mobi/blog/
     &table=postviews
     &end=2024-10-07
     &days=1
     &limit=-1

That gets all of the statistics from one specific day. The limit=-1 means it will retrieve all the records of that day¹.

That will get you a CSV which looks like:

"date","post_id","post_title","post_permalink","views"
"2024-10-09",0,"Home page","https://shkspr.mobi/blog/",59
"2024-10-09",42171,"Review: HP's smallest laser printer - M140w + Linux set up","https://shkspr.mobi/blog/2022/04/review-hps-smallest-laser-printer-m140w-linux-set-up/",7
"2024-10-09",49269,"No, Oscar Wilde did not say ""Imitation is the sincerest form of flattery that mediocrity can pay to greatness""","https://shkspr.mobi/blog/2024/01/no-oscar-wilde-did-not-say-imitation-is-the-sincerest-form-of-flattery-that-mediocrity-can-pay-to-greatness/",7
"2024-10-09",53333,"The Cleaner 🆚 Der Tatortreiniger - Series 3","https://shkspr.mobi/blog/2024/10/the-cleaner-%f0%9f%86%9a-der-tatortreiniger-series-3/",7
"2024-10-09",49943,"Solved! ""Access Point Name settings are not available for this user""","https://shkspr.mobi/blog/2024/03/solved-access-point-name-settings-are-not-available-for-this-user/",7
"2024-10-09",43690,"WhatsApp Web for Android - a reasonable compromise?","https://shkspr.mobi/blog/2022/11/whatsapp-web-for-android-a-reasonable-compromise/",5

You can also get a JSON file using &format=json, although it doesn't contain the permalinks.

[
    {
        "date": "2024-10-09",
        "postviews": [
            {
                "post_id": 0,
                "post_title": "",
                "permalink": "",
                "views": 59
            },
            {
                "post_id": 49269,
                "post_title": "No, Oscar Wilde did not say \"Imitation is the sincerest form of flattery that mediocrity can pay to greatness\"",
                "permalink": "",
                "views": 9
            },
            {
                "post_id": 42171,
                "post_title": "Review: HP's smallest laser printer - M140w + Linux set up",
                "permalink": "",
                "views": 7
            },

From there, I wrote a scrap of Python to download every single date individually.

import requests
import datetime
import os
import json

# Directory to save the JSON files
save_dir = "jetpack_stats"
os.makedirs(save_dir, exist_ok=True)

# URL of the API
base_url = "https://stats.wordpress.com/csv.php?api_key=123456789012"+\
           "&blog_uri=https://example.com/"+\
           "&table=postviews"+\
           "&days=1"+\
           "&format=json"+\
           "&limit=-1"+\
           "&end="

# Make API call and save the response
def fetch_and_save_json(date):
    # Format the date as ISO8601 (YYYY-MM-DD)
    formatted_date = date.isoformat()

    # Make the API call
    url = f"{base_url}{formatted_date}"
    response = requests.get(url)

    if response.status_code == 200:
        data = response.json()
        file_name = f"{formatted_date}.json"
        file_path = os.path.join(save_dir, file_name)
        with open(file_path, "w") as f:
            json.dump(data, f, indent=4)

        print(f"Saved {formatted_date}")
    else:
        print(f"Failed! {formatted_date} status code: {response.status_code}")

# Iterate over a date range
start_date = datetime.date(2023,  1 , 1)
end_date   = datetime.date(2024, 10, 30)

# Loop through all dates 
current_date = start_date
while current_date <= end_date:
    fetch_and_save_json(current_date)
    current_date += datetime.timedelta(days=1)

You'll need to manually find the earliest date for which your blog has statistics.

Running the code is a little slow. Expect about 3 minutes per year of data. I'm sure you could parallelise it if you really needed to.

Now, for my next trick, how do I import these data into a new stats plugin? That's tomorrow's blog post!

Problem

You installed the WordPress JetPack plugin and wrote all your blog posts in Markdown. Now you want to remove JetPack or replace it with a better Markdown parser.

You turn off JetPack's "Write posts or pages in plain-text Markdown syntax". You click edit on a post and see the HTML version of your page. Where did the Markdown version go?

Background

When you write using JetPack's Markdown plugin, the Markdown version is stored in post_content_filtered. When you hit "publish" or "update", the page is parsed as Markdown and the HTML output is stored in post_content.

When you hit "edit", the post_content_filtered version is loaded into the editor - and the process starts again.

Solution

When you edit a post, replace the content with the filtered version, then delete the filtered version.

Place this code in your theme's functions.php.

function edit_markdown_content( $content, $id ) {
    $post = get_post( $id );
    if ( $post && ! empty( $post->post_content_filtered ) ) {
        //  Get the Markdown version
        $markdown = $post->post_content_filtered;

        //  Delete the post_content_filtered version
        global $wpdb;
        $debug = $wpdb->query( 
            $wpdb->prepare(
                "UPDATE $wpdb->posts SET `post_content_filtered` = '' WHERE `wp_posts`.`ID` = %d",
                                                                                              $id
            )
        );

        //  Replace the post_content with the Markdown version
        $post->post_content = $markdown;

        //  Send it to the editor with a message saying that it was restored, along with the date of restoration
        return "<!-- Restored from post_content_filtered \n" . date("c") . "\n-->" . $post->post_content;
    }
    return $post->post_content;
}
add_filter( "edit_post_content", "edit_markdown_content", 1, 2 );

I adapted it from WP Githuber MD

Direct MySQL

If you want to automatically convert all your posts, you can edit your database directly.

UPDATE wp_posts
SET 
    post_content = post_content_filtered,
    post_content_filtered = ''
WHERE post_content_filtered IS NOT NULL AND post_content_filtered<>'';

Warning

If you do not have a Markdown parser installed, posts will come out looking *very* strange.

So here's how I went from this:

To this:

Documentation

The complete documentation for related posts is pretty easy to follow.

This is an adaptation of "Use Jetpack_RelatedPosts_Raw to build your own list of Related Posts".

Remove the automatic placement

You can turn off the original "related posts" by adding this to your theme's functions.php:

function jetpackme_remove_rp() {
    if ( class_exists( 'Jetpack_RelatedPosts' ) ) {
        $jprp = Jetpack_RelatedPosts::init();
        $callback = array( $jprp, 'filter_add_target_to_dom' );
        remove_filter( 'the_content', $callback, 40 );
    }
}
add_filter( 'wp', 'jetpackme_remove_rp', 20 );

Add the new Related Posts

In your theme's index.php (or wherever else you like) you can add this code to insert the new related posts functionality:

if ( is_single() ) {
    echo "<section>";
        echo do_shortcode( '[jprelp]' );
    echo "</section>";
}

Create the new functionality

And this goes in your theme's functions.php file. I've commented it as best I can. Let me know if you need more info.

function jetpackme_custom_related() {
    //  Check that JetPack Related Posts exists
    if (
            class_exists( 'Jetpack_RelatedPosts' )
            && method_exists( 'Jetpack_RelatedPosts', 'init_raw' )
    ) {
            //  Get the related posts
            $related = Jetpack_RelatedPosts::init_raw()
                ->set_query_name( 'edent-related-shortcode' ) 
                ->get_for_post_id(
                    get_the_ID(),   //  ID of the post
                    array( 'size' => 4 )//  How many related items to fetch
                );
            if ( $related ) {
                //  Set the container for the related posts
                $output = "<h2 id='related-posts'>The Algorithm™ suggests:</h2>";
                $output .=   "<ul class='related-posts'>";

                foreach ( $related as $result ) {
                    $related_post_id = $result['id'];

                    // Get the related post
                    $related_post = get_post( $related_post_id );

                    //  Get the attributes
                    $related_post_title = $related_post->post_title;
                    $related_post_date  = substr( $related_post->post_date, 0, 4 ); // YYYY-MM-DD
                    $related_post_link  = get_permalink( $related_post_id );

                    //  Get the thumbnail
                    if ( has_post_thumbnail( $related_post_id) ) {
                        $related_post_thumb = get_the_post_thumbnail( $related_post_id, 'full', 
                            array( "class"   => "related-post-img",
                                   "loading" => "lazy" //   Lazy loading and other attributes
                            ) 
                        );
                    } else {
                        $related_post_thumb = null;
                    }

                    //  Create the HTML for the related post
                    $output .= '<li class="related-post">';
                    $output .=    "<a href='{$related_post_link}'>";
                    $output .=       "{$related_post_thumb}<p>{$related_post_title}</p></a>";
                    $output .=    "<time>{$related_post_date}</time>";
                    $output .= "</li>";
                }
                //  Finish the related posts container
                $output .="</ul>";
            }
        //  Display the related posts
        echo $output;
    }
}
add_shortcode( 'jprel', 'jetpackme_custom_related' );   //  Shortcode name can be whatever you want

Bit of CSS to zhuzh it up

Feel free to add your own styles. This is what works for me.

.related-posts  {
    list-style: none;
    padding: 0;
    display: inline-flex;
    width: 100%;
    flex-wrap: wrap;
    justify-content: center;
}

.related-posts > * {
    /* https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flexible_box_layout/Controlling_ratios_of_flex_items_along_the_main_axis#combining_flex-grow_and_flex-basis */
    flex: 1 1 0;
}

    .related-post {
        min-width: 10em;
        max-width: 20em;
        text-align: center;
        margin: .25em;
        border: .1em var(--color-text);
        border-style: solid;
        border-radius: var(--border-radius);
        position: relative;
        display: flex;
        flex-direction: column;
        min-height: 100%;
        overflow: clip;
    }

        .related-post h3 {
            font-size: 1em;
            padding-top: .5em;
        }

        .related-post img {
            object-fit: cover;
            height: 9em;
            width: 100%;
            border-radius: 0 1em 0 0;
            background: var(--color-text);
            display: inline-block;
        }
        .related-post p {
            margin: 0 .25em;
        }
        .related-post time {
            font-size: .75em;
            display: block;
        }

ToDo

• Use transients to store the data to prevent repeated slow API calls?
• Perhaps some teaser text?
• Adjust the layout so the date always floats to the bottom?

I want to be able to display something like "Join 1,234 subscribers and receive updates via email". So, how do I get the subscriber count from the API?

As documented in the JetPack HTTP API, it is possible to interact with JetPack programmatically.

A good starting point is /wp-json/ - that will show you all the API endpoints available on your blog.

By filtering on "subscribers", we find:

"/jetpack/v4/stats-app/sites/12345/subscribers/counts": {
    "namespace": "jetpack/v4/stats-app",
    "methods": ["GET"],
    "endpoints": [{
        "methods": ["GET"],
        "args": []
    }],
    "_links": {
        "self": [{
            "href": "https://shkspr.mobi/blog/wp-json/jetpack/v4/stats-app/sites/12345/subscribers/counts"
        }]
    }
},

Can we just visit that URl and get the data? Nope!

If you're logged in to your blog, and on the JetPack dashboard, you can run this scrap of Javascript in your browser's console:

fetch( '/wp-json/jetpack/v4/stats-app/sites/12345/subscribers/counts', {
    credentials: 'same-origin',
    headers: {
        'X-WP-Nonce': Initial_State.WP_API_nonce,
        'Content-type': 'application/json' }
} )
    .then( response => response.json() )
    .then( response => console.log( response) )
    .catch( error => console.log( error.responseText ) );

That returns:

{
  "counts": {
    "email_subscribers": 443,
    "social_followers": 0,
    "paid_subscribers": 0
  }
}

OK! So we know it is possible for an admin to get these data. How can we regularly fetch the count from the API and cache it for later use?

Well, that's where I get stuck. The documentation for the WordPress REST API says this:

It is important to keep in mind that this authentication method relies on WordPress cookies. As a result this method is only applicable when the REST API is used inside of WordPress and the current user is logged in. In addition, the current user must have the appropriate capability to perform the action being performed.

So we're stuck without a cookie? Not quite!

The documentation also says we can use Application Passwords. You can read more about them but, basically, go to your user profile screen at /wp-admin/profile.php and you should be able to generate an app password.

Once done, you can test it by running this on the command line:

curl --user "admin:p4ssw0rd" https://example.com/wp-json/jetpack/v4/stats-app/sites/1234/subscribers/counts

(Obviously, use your own username, password, URl, and site ID.)

This means we can add something like this to our functions.php file to get the data and store it for a day:

<?php
if( get_transient( 'jp_sub_stats' ) ) {
    $jp_sub_stats = get_transient( 'jp_sub_stats' );
} else {
    $headers = array(
        'Authorization' => 'Basic ' . base64_encode( 'admin:p4ssw0rd' )
    );

    $api_url = 'https://example.com/wp-json/jetpack/v4/stats-app/sites/1234/subscribers/counts';

    $response = wp_remote_request(
        $api_url,
        array( 'headers'   => $headers )
    );

    $json = json_decode( $response );
    $count = $json->counts->email_subscribers;

    set_transient( 'jp_sub_stats', $count, DAY_IN_SECONDS );
}

Of course, you'll probably want to store the password somewhere securely rather than in your source code. And you'll probably want to do some error checking on what the API returns.

But, there you go. A somewhat convoluted way to get your JetPack subscriber count via an API call. Enjoy!

The Easy Way

Oh! You wanted to do this with the minimum of fuss?

There's a built in function which stores the count in a transient.

So you can simply do:

$cache_key  = 'wpcom_subscribers_total';
$subs       = get_transient( $cache_key );
$subs_count = $subs["value"];

The Problem

Using WordPress's JetPack, markdown footnotes are rendered as:

Some text <sup id="fnref-1234-1"><a href="https://shkspr.mobi/blog/2021/10/better-footnotes-in-wordpress-jetpack/#fn-1234-1" class="jetpack-footnote">1</a></sup>
...
<li id="fn-1234-1">The footnotes. <a href="https://shkspr.mobi/blog/2021/10/better-footnotes-in-wordpress-jetpack/#fnref-1234-1">↩</a></li>

There are two main problems with this:

1. The <sup>1</sup> doesn't announce the destination of the link.
2. The ↩ may be read out as "leftwards arrow with hook"

Ideally, it would be useful to have something like:

<a href="https://shkspr.mobi/blog/2021/10/better-footnotes-in-wordpress-jetpack/#fn-1234-1" aria-label="Read footnote 1" ...

and

<a href="https://shkspr.mobi/blog/2021/10/better-footnotes-in-wordpress-jetpack/#fnref-1234-1" aria-label="Return to main content">↩</a>

Or similar.

The Solution

The issue occurs in jetpack/_inc/lib/markdown/extra.php

@define( 'MARKDOWN_FN_LINK_TITLE',     "" );
@define( 'MARKDOWN_FN_BACKLINK_TITLE', "" );

The link and backlink titles are used later in the same file to set the title.

if ($this->fn_backlink_title != "") {
    $title = $this->fn_backlink_title;
    $title = $this->encodeAttribute($title);
    $attr .= " title=\"$title\"";
}

But, because they're never set, the code doesn't run.

It's pretty easy to hotfix this. Replace the above definitions with:

@define( 'MARKDOWN_FN_LINK_TITLE',     __( 'Read footnote.', 'jetpack' ) );
@define( 'MARKDOWN_FN_BACKLINK_TITLE', __( 'Return to main content.', 'jetpack' ) );

I've raised this as an issue on GitHub.

Problems with the solution.

• It will be overwritten when JetPack updates. You can also add the new @defines to your theme if you want them to survive updates.
• I'm not sure if title is the right element. Although it seems has the same precedence as aria-label in the Accessible Name and Description Computation algorithm
• It is in English only. Because those strings don't exit in the translation file, it will only work for monolingual installs.
• The title text shows as a pop-up on certain browsers.
• No metadata. It might be nice to have the title say "Read footnote 23."
• Some footnote plugins put the footnote text in the title. That may be useful.

If you'd like to see this in the default JetPack experience - please leave a comment on GitHub.