WordPress's undocumented stats API
By @edent
· api WordPress · 2 comments · 400 words · read ~233 times.
This blog runs on WordPress. Using their JetPack plugin, I get fairly detailed stats on views and visitors. But, bizarrely, the API is undocumented. Well, sort of... Let me explain:
Just Show Me The Code
Here's the API call to get a year's worth of data about your blog.
https://public-api.wordpress.com/rest/v1.1/sites/shkspr.mobi::blog/stats/visits
?unit=day
&date=2021-01-03
&quantity=365
&stat_fields=views%2Cvisitors'Replace shkspr.mobi::blog with your blog's ID as found on WordPress. Change the date and quantity as required.
Documentation
If you visit the v1.1 documentation, you won't see any mention of this API call.
There is a similar API call sites/$site/stats/ - but it has no way to control the start date or quantity.
For the actual documentation, we have to look in the archives of the v1 documentation.
Quite why WordPress have hidden the documentation like this, I don't know.
Usage
The API is used to power the https://wordpress.com/stats/year site. If you inspect the network traffic, you'll see the requests and can manipulate them there.
Or you can use the WordPress Developer Console to play around with the API without registering for an API key.
If you can be bothered going through OAuth to get a bearer token, you can call it with curl like:
BASH
curl \
-H 'authorization: Bearer abc123' \
'https://public-api.wordpress.com/rest/v1/sites/shkspr.mobi::blog/stats/visits'
Data
The data back from the API is reasonably straightforward:
JSON
{
"code": 200,
"headers": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"body": {
"date": "2020-12-29",
"unit": "day",
"fields": [
"period",
"views",
"visitors"
],
"data": [
[
"2019-12-31",
959,
746
],
[
"2020-01-01",
953,
717
],
[
"2020-01-02",
1607,
1237
],
The data contains the "rows" of your data, and the fields are the "column headings".
You can then use this to make exciting graphs of your visitor numbers. FUN!!
Not WordPress but Automattic 😉 but yes, that specific call isn’t mentioned. You could open a GH Issue for someone to document it, I can’t offhand think of why it isn’t documented.
Looking at the history of the endpoint, there are some oddities with it ("yearly" values have some known issues, it behaves differently than other endpoints in the stats group, etc) to where the team implementing was not comfortable documenting it for external use.
Since it is undocumented, while I don't see any changes in the foreseeable future, it could change without notice, so just be aware of that before using it for anything important.